Capacitor 7 Background Task Execution Budget and Idempotency Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded Async Execution Without Cancellation Leases and Immediate Completion Signals) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Capacitor 7 Background Task Execution Budget and Idempotency Guardrail

--- description: Capacitor 7 Background Task Execution Budget and Idempotency Guardrail - Enforces deterministic OS battery budget compliance and transactional deduping for periodic background synchronizations bridging iOS BGAppRefreshTask/BGProcessingTask and Android WorkManager via Capacitor 7. Mandates hard execution timeouts with AbortController, idempotent synchronization leases via atomic SQLite/Key-Value stores, and immediate task completion notification to avoid OS SIGKILL termination and app standby deprioritization. globs: src/**/*.{ts,tsx}, ios/App/App/AppDelegate.swift, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-background-task-execution-budget-idempotency" --- # Capacitor 7 Background Task Execution Budget and Idempotency Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Async Execution Without Cancellation Leases and Immediate Completion Signals ## System Constraints You are a Principal Mobile Architect enforcing runtime battery budgeting, deterministic OS lifecycle signaling, and transactional deduplication in Capacitor 7 hybrid mobile applications. Never allow background operations that run open-ended promises or omit platform-level completion handlers. ## Strict Guidelines - Engineers MUST ALWAYS bound all background operations to a strict time limit (maximum 25 seconds for iOS BGAppRefreshTask to protect the 30-second hard kill threshold) using an AbortController. - Engineers MUST ALWAYS invoke `BackgroundTask.finish({ taskId })` inside a `finally` block to ensure native OS signaling occurs even when operations reject or throw. - Services MUST implement transactional idempotency with local persistence (SQLite, Preferences, or Key-Value store) recording task state, unique execution nonce, and TTL before executing external side-effects. - Engineers MUST NOT rely on continuous background execution or unbounded Promise.all calls in background tasks, as iOS watchdog timer will issue a 0x8badf00d termination exception. - Code SHOULD handle Android WorkManager expedited worker quota exhaustion by gracefully degrading to standard periodic work requests with exponential backoff. - Components NEVER start long-running background synchronization without inspecting current battery level and network metered status via `@capacitor/network` and `@capacitor/device`. ## Bad vs Good Implementations ### Unbounded Sync Without Abort Budget vs. Guarded Idempotent Background Task Runner #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to capture the native task ID, lacks an AbortController to cut off execution before the OS 30-second watchdog limit, and does not provide idempotency locks, risking duplicate mutations and process termination by the mobile operating system. ```typescript import { BackgroundTask } from '@capawesome/capacitor-background-task'; import { syncPendingData } from './syncService'; export async function registerBackgroundSync(): Promise<void> { // ANTI-PATTERN: No task registration tracking, no execution budget, no idempotency lock. // If network hangs, iOS watchdog issues SIGKILL (0x8badf00d) after 30 seconds, // and Android WorkManager marks the worker as failed without releasing native locks. await BackgroundTask.beforeExit(async () => { await syncPendingData(); // Can hang indefinitely; never notifies finish reliably }); } ``` #### Production Standard (Correct) > **Standard**: Wraps the background task in a deterministic 25-second execution budget, checks an atomic lease for deduplication across quick resume events, and unconditionally calls BackgroundTask.finish in the finally block to avert OS battery budget penalties. ```typescript import { BackgroundTask } from '@capawesome/capacitor-background-task'; import { Preferences } from '@capacitor/preferences'; import { syncPendingData } from './syncService'; const EXECUTION_BUDGET_MS = 25000; // iOS hard limit is 30s const LOCK_TTL_MS = 60000; export async function executeGuardedBackgroundSync(): Promise<void> { const taskId = await BackgroundTask.beforeExit(async () => { const abortController = new AbortController(); const timeoutId = setTimeout(() => abortController.abort(), EXECUTION_BUDGET_MS); const syncNonce = `sync_lease_${Date.now()}`; try { // Check and set atomic lease in persistent storage const { value: existingLease } = await Preferences.get({ key: 'bg_sync_lease' }); const lastRun = existingLease ? parseInt(existingLease, 10) : 0; if (Date.now() - lastRun < LOCK_TTL_MS) { return; // Deduped: Previous run still holds active lease } await Preferences.set({ key: 'bg_sync_lease', value: Date.now().toString() }); await syncPendingData({ signal: abortController.signal, nonce: syncNonce }); } catch (error: unknown) { if (abortController.signal.aborted) { console.error('Background sync budget exceeded; aborted gracefully.'); } else { console.error('Background task failed:', error); } } finally { clearTimeout(timeoutId); // Deterministically release OS background assertion await BackgroundTask.finish({ taskId }); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Background Task Execution Budget and Idempotency Guardrail

Capacitor 7 Background Task Execution Budget and Idempotency Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic OS battery budget compliance and transactional deduping for periodic background synchronizations bridging iOS BGAppRefreshTask/BGProcessingTask and Android WorkManager via Capacitor 7. Mandates hard execution timeouts with AbortController, idempotent synchronization leases via atomic SQLite/Key-Value stores, and immediate task completion notification to avoid OS SIGKILL termination and app standby deprioritization. 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 Async Execution Without Cancellation Leases and Immediate Completion Signals 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 Async Execution Without Cancellation Leases and Immediate Completion Signals	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 all background operations to a strict time limit (maximum 25 seconds for iOS BGAppRefreshTask to protect the 30-second hard kill threshold) using an 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.