BackgroundTasks

System-scheduled background work on Apple platforms via BGTaskScheduler — app refresh, processing, and continued processing. The deep API reference — setup, registration, scheduling, execution, testing, iOS 18/26 additions, and every use case — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. TASK_TYPE — app-refresh (BGAppRefreshTask, ~30s, lightweight content freshness) · processing (BGProcessingTask, minutes, maintenance/ML/large sync) · continued (iOS 26 BGContinuedProcessingTask, user-initiated, progress-reporting, cancellable).
2. CONSTRAINTS — only on processing: requiresNetworkConnectivity (run only with network) · requiresExternalPower (run only while charging). continued uses requiredResources (e.g. .gpu) instead.
3. SCHEDULING — opportunistic (default; submit a request with earliestBeginDate, system picks the moment) · immediate (only continued via SubmissionStrategy.fail, which throws immediateRunIneligible if the system can't start now).

When to use

Building or reviewing any code that schedules deferred work to run while the app is backgrounded or suspended — content sync, widget refresh, DB maintenance, cache cleanup, ML updates, or a user-started export that should finish in the background. Not for keeping a foreground session alive (use beginBackgroundTask) and not for guaranteed/timely delivery (the system decides if and when).

Core rules