@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/background-processing/SKILL.md

@@ -1,500 +1,390 @@
 ---
 name: background-processing
-description: "Schedule and execute background work on iOS using BGTaskScheduler. Use when registering BGAppRefreshTask for short background fetches, BGProcessingTask for long-running maintenance, BGContinuedProcessingTask (iOS 26+) for foreground-started work that continues in background, background URLSession downloads, or background push notifications. Covers Info.plist configuration, expiration handling, task completion, and debugging with simulated launches."
+description: "iOS background work with BGTaskScheduler: BGAppRefreshTask short fetches, BGProcessingTask long maintenance, BGContinuedProcessingTask (iOS 26+) for user-started work, background URLSession transfers, silent pushes, Info.plist identifiers and modes, handler registration, expiration and completion, simulated launches for debugging. Use when adding, reviewing or debugging background work. Not for visible notification UI."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
+
 # Background Processing
 
-Register, schedule, and execute background work on iOS using the BackgroundTasks
-framework, background URLSession, and background push notifications.
+iOS gives an app background time only on its own terms. You describe the work,
+the system chooses the moment, or skips it entirely, and your code has to finish
+or stop cleanly whenever it is told to. This skill covers the BackgroundTasks
+framework, background `URLSession` transfers and silent pushes.
 
-## Contents
+Covers: background `URLSession` downloads and uploads. Not for designing
+visible notification UI.
 
-- [Info.plist Configuration](#infoplist-configuration)
-- [BGTaskScheduler Registration](#bgtaskscheduler-registration)
-- [BGAppRefreshTask Patterns](#bgapprefreshtask-patterns)
-- [BGProcessingTask Patterns](#bgprocessingtask-patterns)
-- [BGContinuedProcessingTask (iOS 26+)](#bgcontinuedprocessingtask-ios-26)
-- [Background URLSession Downloads](#background-urlsession-downloads)
-- [Background Push Triggers](#background-push-triggers)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+## Configuration
 
-## Info.plist Configuration
+**Permitted identifiers.** Every task identifier goes into the Info.plist
+array `BGTaskSchedulerPermittedIdentifiers`. A missing entry makes
+`submit(_:)` throw `BGTaskScheduler.Error.Code.notPermitted`. An entry may end
+in a wildcard, such as `org.sample.photos.export.*`, for per-job identifiers.
 
-Every task identifier **must** be declared in `Info.plist` under
-`BGTaskSchedulerPermittedIdentifiers`, or `submit(_:)` throws
-`BGTaskScheduler.Error.Code.notPermitted`.
+**Background modes.** `UIBackgroundModes` needs `fetch` for app refresh tasks
+and `processing` for processing tasks. In Xcode: target, Signing &
+Capabilities, Background Modes, then tick "Background fetch" and "Background
+processing".
 
 ```xml
 <key>BGTaskSchedulerPermittedIdentifiers</key>
 <array>
-    <string>com.example.app.refresh</string>
-    <string>com.example.app.db-cleanup</string>
-    <string>com.example.app.export.*</string>
+    <string>org.sample.photos.refresh</string>
+    <string>org.sample.photos.cleanup</string>
+    <string>org.sample.photos.export.*</string>
 </array>
-```
-
-Also enable the required `UIBackgroundModes`:
-
-```xml
 <key>UIBackgroundModes</key>
 <array>
-    <string>fetch</string>       <!-- Required for BGAppRefreshTask -->
-    <string>processing</string>  <!-- Required for BGProcessingTask -->
+    <string>fetch</string>
+    <string>processing</string>
 </array>
 ```
 
-In Xcode: target > Signing & Capabilities > Background Modes > enable "Background fetch" and "Background processing".
-
-## BGTaskScheduler Registration
+## Registering handlers
 
-Register handlers **before** app launch completes. In UIKit, register in
-`application(_:didFinishLaunchingWithOptions:)`; in SwiftUI, register in `App.init()`.
-
-### UIKit Registration
+Refresh and processing handlers must be registered before the app finishes
+launching: in `application(_:didFinishLaunchingWithOptions:)` for UIKit, or in
+the `App` initializer for SwiftUI. Registering later, for instance from a
+view's `.task`, is too late for the system to deliver a launch. Continued
+processing tasks are the one exception, covered below. Register each
+identifier once: a second registration of the same identifier kills the app.
 
 ```swift
 import BackgroundTasks
+import SwiftUI
 
-@main
-class AppDelegate: UIResponder, UIApplicationDelegate {
-    func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-    ) -> Bool {
-        BGTaskScheduler.shared.register(
-            forTaskWithIdentifier: "com.example.app.refresh",
-            using: nil  // nil = default background queue
-        ) { task in
-            self.handleAppRefresh(task: task as! BGAppRefreshTask)
-        }
-
-        BGTaskScheduler.shared.register(
-            forTaskWithIdentifier: "com.example.app.db-cleanup",
-            using: nil
-        ) { task in
-            self.handleDatabaseCleanup(task: task as! BGProcessingTask)
-        }
-
-        return true
-    }
+enum TaskID {
+    static let refresh = "org.sample.photos.refresh"
+    static let cleanup = "org.sample.photos.cleanup"
 }
-```
-
-### SwiftUI Registration
-
-```swift
-import SwiftUI
-import BackgroundTasks
 
 @main
-struct MyApp: App {
+struct PhotosApp: App {
     init() {
-        BGTaskScheduler.shared.register(
-            forTaskWithIdentifier: "com.example.app.refresh",
-            using: nil
-        ) { task in
-            BackgroundTaskManager.shared.handleAppRefresh(
-                task: task as! BGAppRefreshTask
-            )
+        BGTaskScheduler.shared.register(forTaskWithIdentifier: TaskID.refresh, using: nil) { task in
+            guard let refresh = task as? BGAppRefreshTask else { return }
+            LibrarySync.shared.handleRefresh(refresh)
+        }
+        BGTaskScheduler.shared.register(forTaskWithIdentifier: TaskID.cleanup, using: nil) { task in
+            guard let cleanup = task as? BGProcessingTask else { return }
+            LibrarySync.shared.handleCleanup(cleanup)
         }
     }
 
     var body: some Scene {
-        WindowGroup { ContentView() }
+        WindowGroup {
+            LibraryView()
+        }
     }
 }
 ```
 
-## BGAppRefreshTask Patterns
+Passing `nil` for `using:` runs the handler on a default background queue.
+
+## App refresh tasks
 
-Short-lived tasks (~30 seconds) for fetching small data updates. The system
-decides when to launch based on usage patterns. Review notes should say
-`earliestBeginDate` is a lower-bound hint and the system may run the task later.
+A refresh task gets roughly 30 seconds for a small update. The system picks
+the moment based on how the user uses the app. `earliestBeginDate` only says
+"not before"; the task may run much later or not at all, and reviews should
+treat it that way.
 
 ```swift
-func scheduleAppRefresh() {
-    let request = BGAppRefreshTaskRequest(
-        identifier: "com.example.app.refresh"
-    )
-    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
-    // earliestBeginDate is a lower-bound hint; the system may delay launch.
-    do {
-        try BGTaskScheduler.shared.submit(request)
-    } catch {
-        print("Could not schedule app refresh: \(error)")
+final class LibrarySync: Sendable {
+    static let shared = LibrarySync()
+
+    func scheduleRefresh() {
+        let request = BGAppRefreshTaskRequest(identifier: TaskID.refresh)
+        request.earliestBeginDate = .now.addingTimeInterval(15 * 60)
+        if (try? BGTaskScheduler.shared.submit(request)) == nil {
+            Log.background.error("Refresh request was rejected")
+        }
     }
-}
 
-func handleAppRefresh(task: BGAppRefreshTask) {
-    // Schedule the next refresh before doing work
-    scheduleAppRefresh()
-
-    let fetchTask = Task {
-        do {
-            let data = try await APIClient.shared.fetchLatestFeed()
-            await FeedStore.shared.update(with: data)
-            task.setTaskCompleted(success: true)
-        } catch {
-            task.setTaskCompleted(success: false)
-        }
+    func handleRefresh(_ task: BGAppRefreshTask) {
+        scheduleRefresh()
+        perform(task) { try await self.fetchNewAlbums() }
     }
+}
 
-    // CRITICAL: Handle expiration -- system can revoke time at any moment
-    task.expirationHandler = {
-        fetchTask.cancel()
-        task.setTaskCompleted(success: false)
+func perform(_ task: BGTask, _ job: @escaping @Sendable () async throws -> Void) {
+    nonisolated(unsafe) let task = task
+    let work = Task {
+        let finished = (try? await job()) != nil
+        task.setTaskCompleted(success: finished && !Task.isCancelled)
     }
+    task.expirationHandler = { work.cancel() }
 }
 ```
 
-## BGProcessingTask Patterns
+`Log.background` stands for an `os.Logger` owned by the app, and the
+processing example below reuses `perform`. Two habits matter: schedule the
+next run first, so a crash or expiry does not break the chain, and always
+install an `expirationHandler`, because the system can take the time back at
+any moment. The handler only cancels; the work `Task` is the one completion
+path, so `setTaskCompleted(success:)` runs exactly once, with `false` after an
+expiry. That relies on the job honouring cancellation (`URLSession` async calls
+and `Task.checkCancellation()` throw), so the `Task` ends soon after the
+handler fires.
 
-Long-running tasks (minutes) for maintenance, data processing, or cleanup.
-Runs only when device is idle and (optionally) charging. Review notes should say
-`earliestBeginDate` is a lower-bound hint and the system may run the task later.
+`BGTask` is not `Sendable`, yet both the work `Task` and the expiration
+handler need it, and the handler runs on a queue the framework picks. The
+`nonisolated(unsafe)` local copy marks that sharing as deliberate; without it
+Swift 6 rejects the `Task` closure with "passing closure as a 'sending'
+parameter risks causing data races".
+
+## Processing tasks
+
+Processing tasks can run for minutes and suit maintenance, indexing and
+cleanup. They start only while the device is idle, and optionally only on
+power.
 
 ```swift
-func scheduleProcessingTask() {
-    let request = BGProcessingTaskRequest(
-        identifier: "com.example.app.db-cleanup"
-    )
+func scheduleCleanup() {
+    let request = BGProcessingTaskRequest(identifier: TaskID.cleanup)
     request.requiresNetworkConnectivity = false
     request.requiresExternalPower = true
-    request.earliestBeginDate = Date(timeIntervalSinceNow: 60 * 60)
-    // earliestBeginDate is a lower-bound hint; the system may delay launch.
-    do {
-        try BGTaskScheduler.shared.submit(request)
-    } catch {
-        print("Could not schedule processing task: \(error)")
-    }
+    request.earliestBeginDate = .now.addingTimeInterval(3600)
+    try? BGTaskScheduler.shared.submit(request)
 }
 
-func handleDatabaseCleanup(task: BGProcessingTask) {
-    scheduleProcessingTask()
-
-    let cleanupTask = Task {
-        do {
-            try await DatabaseManager.shared.purgeExpiredRecords()
-            try await DatabaseManager.shared.rebuildIndexes()
-            task.setTaskCompleted(success: true)
-        } catch {
-            task.setTaskCompleted(success: false)
-        }
-    }
-
-    task.expirationHandler = {
-        cleanupTask.cancel()
-        task.setTaskCompleted(success: false)
-    }
+func handleCleanup(_ task: BGProcessingTask) {
+    scheduleCleanup()
+    perform(task) { try await purgeOrphanedThumbnails() }
 }
 ```
 
-## BGContinuedProcessingTask (iOS 26+)
+## Continued processing tasks (iOS 26+)
 
-A task initiated in the foreground by a user action that continues running in the
-background. The system displays progress via a Live Activity. Conforms to
-`ProgressReporting`.
+`BGContinuedProcessingTask` needs iOS or iPadOS 26.0 and is for work the user
+starts on purpose, such as an export, that should keep going after they leave
+the app. It differs from the other two types:
 
-**Availability:** iOS 26.0+, iPadOS 26.0+
-
-Unlike `BGAppRefreshTask` and `BGProcessingTask`, this task starts immediately
-from the foreground. The system can terminate it under resource pressure,
-prioritizing tasks that report minimal progress first. Set `expirationHandler` for user or system cancellation, cancel in-flight work, and clean up partial output before reporting completion.
+- It starts right away from the foreground instead of waiting for the system.
+- The system shows its progress to the user as a Live Activity; the task
+  adopts `ProgressReporting`.
+- Under resource pressure the system may end it, and tasks reporting little
+  progress go first.
+- The user or the system can cancel it; the `expirationHandler` must stop the
+  work and remove partial output, and the cancelled work then completes once.
+- Its handler is exempt from the register-at-launch rule. `submit` expects
+  an identifier that already has a handler, so register the job's identifier
+  right before submitting it.
 
 ```swift
-import BackgroundTasks
-
-func startExport() {
-    // Register the task handler at app launch, not here.
-    // BGTaskScheduler requires registration before app launch completes.
-    let jobID = UUID().uuidString
+func startExport(of album: Album) {
+    let identifier = "org.sample.photos.export.\(UUID().uuidString)"
+    BGTaskScheduler.shared.register(forTaskWithIdentifier: identifier, using: nil) { task in
+        guard let export = task as? BGContinuedProcessingTask else { return }
+        handleExport(export)
+    }
     let request = BGContinuedProcessingTaskRequest(
-        identifier: "com.example.app.export.\(jobID)",
-        title: "Exporting Photos",
-        subtitle: "Processing 247 items"
+        identifier: identifier,
+        title: "Exporting \(album.name)",
+        subtitle: "Preparing"
     )
-    // Use a permitted base wildcard identifier: com.example.app.export.*
-    // earliestBeginDate is ignored for continued processing requests.
-    // .queue: begin as soon as possible if can't run immediately
-    // .fail: fail submission if can't run immediately
-    request.strategy = .queue
-
-    do {
-        try BGTaskScheduler.shared.submit(request)
-    } catch {
-        print("Could not submit continued processing task: \(error)")
+    request.strategy = .fail
+    if BGTaskScheduler.supportedResources.contains(.gpu) {
+        request.requiredResources = .gpu
+    }
+    guard (try? BGTaskScheduler.shared.submit(request)) != nil else {
+        showExportUnavailable()
+        return
     }
 }
 
-func performExport(task: BGContinuedProcessingTask) async {
-    let items = await PhotoLibrary.shared.itemsToExport()
-    let progress = task.progress
-    progress.totalUnitCount = Int64(items.count)
-
-    for (index, item) in items.enumerated() {
-        if Task.isCancelled { break }
-
-        await PhotoExporter.shared.export(item)
-        progress.completedUnitCount = Int64(index + 1)
-
-        // Update the user-facing title/subtitle
-        task.updateTitle(
-            "Exporting Photos",
-            subtitle: "\(index + 1) of \(items.count) complete"
-        )
+func handleExport(_ task: BGContinuedProcessingTask) {
+    nonisolated(unsafe) let task = task
+    let work = Task { await runExport(task, items: ExportQueue.shared.pending) }
+    task.expirationHandler = {
+        work.cancel()
+        ExportQueue.shared.removePartialFiles()
     }
+}
 
+func runExport(_ task: BGContinuedProcessingTask, items: [PhotoAsset]) async {
+    task.progress.totalUnitCount = Int64(items.count)
+    var done: Int64 = 0
+    for asset in items where !Task.isCancelled {
+        await render(asset)
+        done += 1
+        task.progress.completedUnitCount = done
+        task.updateTitle(task.title, subtitle: "Photo \(done) of \(items.count)")
+    }
     task.setTaskCompleted(success: !Task.isCancelled)
 }
 ```
 
-For GPU work, check support and enable Background GPU Access (`com.apple.developer.background-tasks.continued-processing.gpu`):
+When the task expires, the cancelled `Task` leaves the loop and
+`runExport` reports `success: false`, so completion still happens exactly once. The
+`nonisolated(unsafe)` copy in `handleExport` is there for the same reason as in
+`perform`.
 
-```swift
-let supported = BGTaskScheduler.supportedResources
-if supported.contains(.gpu) {
-    request.requiredResources = .gpu
-}
-```
+- Each job gets its own identifier under a permitted wildcard base, which
+  also keeps every registration unique.
+- `earliestBeginDate` is ignored for this request type.
+- `strategy` is `.queue` (start as soon as allowed) or `.fail` (reject the
+  submission if it cannot start now).
+- GPU work needs both the `supportedResources` check and the entitlement for
+  background GPU use (key ending in `continued-processing.gpu`).
 
-## Background URLSession Downloads
+Strategy choice, cancellation and progress ranking are expanded in the
+[patterns reference](references/background-task-patterns.md).
 
-Use `URLSessionConfiguration.background` for downloads that continue even after
-the app is suspended or terminated. The system handles the transfer out of
-process.
+## Background URLSession
+
+A session built with `URLSessionConfiguration.background(withIdentifier:)`
+hands transfers to a system daemon, so they keep running while the app is
+suspended or even terminated.
 
 ```swift
-class DownloadManager: NSObject, URLSessionDownloadDelegate {
-    static let shared = DownloadManager()
+@MainActor
+final class EpisodeDownloader: NSObject, URLSessionDownloadDelegate {
+    static let shared = EpisodeDownloader()
+
+    var finishEvents: (() -> Void)?
 
-    private lazy var session: URLSession = {
+    lazy var session: URLSession = {
         let config = URLSessionConfiguration.background(
-            withIdentifier: "com.example.app.background-download"
+            withIdentifier: "org.sample.podcasts.downloads"
         )
-        config.isDiscretionary = true
         config.sessionSendsLaunchEvents = true
-        return URLSession(configuration: config, delegate: self, delegateQueue: nil)
+        config.isDiscretionary = true
+        return URLSession(
+            configuration: config,
+            delegate: self,
+            delegateQueue: nil
+        )
     }()
 
-    func startDownload(from url: URL) {
-        let task = session.downloadTask(with: url)
-        task.earliestBeginDate = Date(timeIntervalSinceNow: 60)
-        task.resume()
+    func fetch(_ remote: URL, notBefore date: Date? = nil) {
+        let job = session.downloadTask(with: remote)
+        job.earliestBeginDate = date
+        job.resume()
     }
 
-    func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didFinishDownloadingTo location: URL
-    ) {
-        // Move file from tmp before this method returns
-        let dest = FileManager.default.urls(
-            for: .documentDirectory, in: .userDomainMask
-        )[0].appendingPathComponent("download.dat")
-        try? FileManager.default.moveItem(at: location, to: dest)
+    nonisolated func urlSession(_ s: URLSession, downloadTask job: URLSessionDownloadTask, didFinishDownloadingTo tmp: URL) {
+        let name = job.response?.suggestedFilename ?? "episode-\(job.taskIdentifier)"
+        let target = URL.documentsDirectory.appending(path: name)
+        try? FileManager.default.moveItem(at: tmp, to: target)
     }
 
-    func urlSession(
-        _ session: URLSession,
-        task: URLSessionTask,
-        didCompleteWithError error: (any Error)?
-    ) {
-        if let error { print("Download failed: \(error)") }
+    nonisolated func urlSession(_ s: URLSession, task job: URLSessionTask, didCompleteWithError error: (any Error)?) {
+        guard let error else { return }
+        Log.background.error("Transfer failed: \(error)")
     }
-}
-```
-
-Handle app relaunch  -  store and invoke the system completion handler:
-
-```swift
-// In AppDelegate:
-func application(
-    _ application: UIApplication,
-    handleEventsForBackgroundURLSession identifier: String,
-    completionHandler: @escaping () -> Void
-) {
-    backgroundSessionCompletionHandler = completionHandler
-}
-
-// In URLSessionDelegate  -  call stored handler when events finish:
-func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
-    Task { @MainActor in
-        self.backgroundSessionCompletionHandler?()
-        self.backgroundSessionCompletionHandler = nil
-    }
-}
-```
-
-## Background Push Triggers
-
-Silent push notifications wake your app briefly to fetch new content. Set
-`content-available: 1` in the push payload.
-
-```json
-{ "aps": { "content-available": 1 }, "custom-data": "new-messages" }
-```
-
-Send the APNs request with `apns-push-type: background` and
-`apns-priority: 5`. Background push delivery is low priority and not
-guaranteed; keep sends infrequent, generally no more than two or three per
-hour.
-
-Handle in AppDelegate:
 
-```swift
-func application(
-    _ application: UIApplication,
-    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
-    fetchCompletionHandler completionHandler:
-        @escaping (UIBackgroundFetchResult) -> Void
-) {
-    Task {
-        do {
-            let hasNew = try await MessageStore.shared.fetchNewMessages()
-            completionHandler(hasNew ? .newData : .noData)
-        } catch {
-            completionHandler(.failed)
+    nonisolated func urlSessionDidFinishEvents(forBackgroundURLSession s: URLSession) {
+        Task { @MainActor in
+            self.finishEvents?()
+            self.finishEvents = nil
         }
     }
 }
 ```
 
-Enable "Remote notifications" in Background Modes and register:
-
-```swift
-UIApplication.shared.registerForRemoteNotifications()
-```
-
-## Common Mistakes
-
-### 1. Missing Info.plist identifiers
-
-```swift
-// DON'T: Submit a task whose identifier isn't in BGTaskSchedulerPermittedIdentifiers
-let request = BGAppRefreshTaskRequest(identifier: "com.example.app.refresh")
-try BGTaskScheduler.shared.submit(request)  // Throws .notPermitted
-
-// DO: Add every identifier to Info.plist BGTaskSchedulerPermittedIdentifiers
-// <string>com.example.app.refresh</string>
-```
+- The class is `@MainActor`, so the lazy session and the stored handler are
+  safe to touch from UIKit callbacks. The session calls its delegate on its
+  own queue, hence the `nonisolated` delegate methods.
+- `isDiscretionary` lets the system wait for good conditions. With
+  `sessionSendsLaunchEvents` on, finished transfers launch the app again.
+- A delegate is required (`delegateQueue: nil` is fine). The async and
+  completion-handler task APIs do not work with background sessions.
+- The temporary file disappears when `didFinishDownloadingTo` returns, so move
+  it inside that method.
+- Failures arrive in `urlSession(_:task:didCompleteWithError:)`.
 
-### 2. Not calling setTaskCompleted(success:)
+When the system relaunches the app for session events, keep the handler it
+gives you and call it once the delegate reports the events are done:
 
 ```swift
-// DON'T: Return without marking completion -- system penalizes future scheduling
-func handleRefresh(task: BGAppRefreshTask) {
-    Task {
-        let data = try await fetchData()
-        await store.update(data)
-        // Missing: task.setTaskCompleted(success:)
-    }
-}
-
-// DO: Always call setTaskCompleted on every code path
-func handleRefresh(task: BGAppRefreshTask) {
-    let work = Task {
-        do {
-            let data = try await fetchData()
-            await store.update(data)
-            task.setTaskCompleted(success: true)
-        } catch {
-            task.setTaskCompleted(success: false)
-        }
-    }
-    task.expirationHandler = {
-        work.cancel()
-        task.setTaskCompleted(success: false)
-    }
+func application(_ app: UIApplication,
+                 handleEventsForBackgroundURLSession id: String,
+                 completionHandler done: @escaping () -> Void) {
+    EpisodeDownloader.shared.finishEvents = done
+    _ = EpisodeDownloader.shared.session
 }
 ```
 
-### 3. Ignoring the expiration handler
+## Background pushes
 
-```swift
-// DON'T: Assume your task will run to completion
-func handleCleanup(task: BGProcessingTask) {
-    Task { await heavyWork() }
-    // No expirationHandler -- system terminates ungracefully
-}
+A silent push wakes the app for a short time. The payload carries
+`content-available: 1` plus your own keys. On the APNs request, set the
+push type header to `background` and the priority header to `5`.
 
-// DO: Set expirationHandler to cancel work and mark completed
-func handleCleanup(task: BGProcessingTask) {
-    let work = Task { await heavyWork() }
-    task.expirationHandler = {
-        work.cancel()
-        task.setTaskCompleted(success: false)
-    }
+```json
+{
+  "aps": { "content-available": 1 },
+  "album-id": "A41"
 }
 ```
 
-### 4. Scheduling too frequently
+Delivery is low priority and never guaranteed. Keep it to two or three per hour
+at most. Enable Remote notifications under Background Modes and call
+`UIApplication.shared.registerForRemoteNotifications()`.
 
 ```swift
-// DON'T: Request refresh every minute -- system throttles aggressively
-request.earliestBeginDate = Date(timeIntervalSinceNow: 60)
-
-// DO: Use reasonable intervals (15+ minutes for refresh)
-request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
-// earliestBeginDate is a hint -- the system chooses actual launch time
-```
-
-### 5. Over-relying on background time
-
-```swift
-// DON'T: Start a 10-minute operation assuming it will finish
-func handleRefresh(task: BGAppRefreshTask) {
-    Task { await tenMinuteSync() }
-}
-
-// DO: Design work to be incremental and cancellable
-func handleRefresh(task: BGAppRefreshTask) {
-    let work = Task {
-        for batch in batches {
-            try Task.checkCancellation()
-            await processBatch(batch)
-            await saveBatchProgress(batch)
-        }
-        task.setTaskCompleted(success: true)
+func application(_ app: UIApplication,
+                 didReceiveRemoteNotification payload: [AnyHashable: Any],
+                 fetchCompletionHandler reply: @escaping (UIBackgroundFetchResult) -> Void) {
+    guard let albumID = payload["album-id"] as? String else {
+        return reply(.noData)
     }
-    task.expirationHandler = {
-        work.cancel()
-        task.setTaskCompleted(success: false)
+    Task {
+        let outcome: Result<Bool, any Error> = await LibrarySync.shared.refreshAlbum(albumID)
+        switch outcome {
+        case .success(true): reply(.newData)
+        case .success(false): reply(.noData)
+        case .failure: reply(.failed)
+        }
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] All task identifiers listed in `BGTaskSchedulerPermittedIdentifiers`
-- [ ] Required `UIBackgroundModes` enabled (`fetch`, `processing`)
-- [ ] Tasks registered before app launch completes
-- [ ] `setTaskCompleted(success:)` called on every code path
-- [ ] `expirationHandler` set and cancels in-flight work
-- [ ] Next task scheduled inside the handler (re-schedule pattern)
-- [ ] `earliestBeginDate` uses reasonable intervals and is treated as a hint
-- [ ] Background URLSession uses delegate (not async/closures)
-- [ ] Background URLSession file moved in `didFinishDownloadingTo` before return
-- [ ] `handleEventsForBackgroundURLSession` stores and calls completion handler
-- [ ] Background push payload includes `content-available: 1`
-- [ ] Background push APNs request uses `apns-push-type: background` and `apns-priority: 5`
-- [ ] `fetchCompletionHandler` called promptly with correct result
-- [ ] BGContinuedProcessingTask reports progress via `ProgressReporting`
-- [ ] Work is incremental and cancellation-safe (`Task.checkCancellation()`)
-- [ ] No blocking synchronous work in task handlers
+## Common mistakes
+
+- **Identifier missing from Info.plist.** `submit` throws `.notPermitted`.
+- **Skipping `setTaskCompleted(success:)`.** The system schedules the app less
+  often afterwards. Complete on every path, errors included.
+- **No expiration handler.** The task is killed abruptly instead of stopping
+  cleanly. Cancel the work from the handler and let the cancelled work report
+  `success: false`, so completion happens once.
+- **Asking too often.** A refresh every minute gets throttled hard. Use 15
+  minutes or more, and remember `earliestBeginDate` is a hint.
+- **Too much work per run.** A ten-minute job inside a refresh task will not
+  finish. Split work into small cancellable batches, call
+  `try Task.checkCancellation()` between them and save progress.
+
+## Review checklist
+
+- [ ] Every identifier is in `BGTaskSchedulerPermittedIdentifiers`
+- [ ] `UIBackgroundModes` has `fetch` and/or `processing` as needed
+- [ ] Refresh and processing handlers are registered before launch completes;
+      continued processing handlers are registered before their `submit`
+- [ ] `setTaskCompleted(success:)` runs exactly once on every path
+- [ ] `expirationHandler` cancels in-flight work
+- [ ] The handler schedules the next task
+- [ ] `earliestBeginDate` is sensible and read as a lower bound only
+- [ ] Background `URLSession` uses a delegate, not async or closure APIs
+- [ ] Downloaded files are moved inside `didFinishDownloadingTo`
+- [ ] `handleEventsForBackgroundURLSession` stores its handler and it is called later
+- [ ] Silent push payload has `content-available: 1`
+- [ ] APNs headers: push type `background`, priority `5`
+- [ ] `fetchCompletionHandler` is called promptly with the right result
+- [ ] Continued processing tasks report progress through `ProgressReporting`
+- [ ] Work is incremental and checks cancellation (`Task.checkCancellation()`)
+- [ ] Handlers never block on synchronous work
 
 ## References
 
-- See [references/background-task-patterns.md](references/background-task-patterns.md) for extended patterns, background
-  URLSession edge cases, debugging with simulated launches, and background push
-  best practices.
-- [BGTaskScheduler](https://sosumi.ai/documentation/backgroundtasks/bgtaskscheduler)
-- [BGAppRefreshTask](https://sosumi.ai/documentation/backgroundtasks/bgapprefreshtask)
-- [BGProcessingTask](https://sosumi.ai/documentation/backgroundtasks/bgprocessingtask)
-- [BGContinuedProcessingTask](https://sosumi.ai/documentation/backgroundtasks/bgcontinuedprocessingtask) (iOS 26+)
-- [BGContinuedProcessingTaskRequest](https://sosumi.ai/documentation/backgroundtasks/bgcontinuedprocessingtaskrequest) (iOS 26+)
-- [Using background tasks to update your app](https://sosumi.ai/documentation/uikit/using-background-tasks-to-update-your-app)
-- [Performing long-running tasks on iOS and iPadOS](https://sosumi.ai/documentation/backgroundtasks/performing-long-running-tasks-on-ios-and-ipados)
+- [Background task patterns](references/background-task-patterns.md):
+  debugging, error codes, checkpointing, URLSession extras, push limits,
+  SwiftUI `.backgroundTask`, continued-processing details
+- Apple documentation:
+  [scheduler](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler),
+  [refresh task](https://developer.apple.com/documentation/backgroundtasks/bgapprefreshtask),
+  [processing task](https://developer.apple.com/documentation/backgroundtasks/bgprocessingtask),
+  [continued processing task](https://developer.apple.com/documentation/backgroundtasks/bgcontinuedprocessingtask) (iOS 26+),
+  [continued processing request](https://developer.apple.com/documentation/backgroundtasks/bgcontinuedprocessingtaskrequest) (iOS 26+),
+  [keeping content fresh with background tasks](https://developer.apple.com/documentation/uikit/using-background-tasks-to-update-your-app),
+  [long-running work](https://developer.apple.com/documentation/backgroundtasks/performing-long-running-tasks-on-ios-and-ipados)