@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/mapkit-location/references/mapkit-corelocation-patterns.md

@@ -1,411 +1,322 @@
-# CoreLocation Patterns Reference
+# CoreLocation Patterns
 
-Extended patterns for CoreLocation on iOS 17+ with modern Swift concurrency.
-Import `CoreLocation` in every file that uses these APIs.
-
-```swift
-import CoreLocation
-```
-
----
+Modern CoreLocation with Swift concurrency, iOS 17 and later unless a heading
+says otherwise. Import `CoreLocation` in each file that uses these types.
 
 ## Contents
 
-- [CLLocationUpdate.liveUpdates() (iOS 17+)](#cllocationupdateliveupdates-ios-17)
-- [CLServiceSession (iOS 18+)](#clservicesession-ios-18)
-- [CLMonitor for Geofencing (iOS 17+)](#clmonitor-for-geofencing-ios-17)
+- [CLLocationUpdate.liveUpdates()](#cllocationupdateliveupdates)
+- [Service Sessions (iOS 18+)](#service-sessions-ios-18)
+- [Geofences with CLMonitor (iOS 17+)](#geofences-with-clmonitor-ios-17)
 - [CLBackgroundActivitySession](#clbackgroundactivitysession)
-- [Significant Location Change Monitoring](#significant-location-change-monitoring)
-- [Visit Monitoring](#visit-monitoring)
-- [Region Monitoring Migration (CLCircularRegion to CLMonitor)](#region-monitoring-migration-clcircularregion-to-clmonitor)
-- [Location Accuracy Management](#location-accuracy-management)
-- [Testing Location in Simulator](#testing-location-in-simulator)
-- [Privacy and Info.plist Keys](#privacy-and-infoplist-keys)
-- [Common Pitfalls](#common-pitfalls)
+- [Coarse Updates from Significant Changes](#coarse-updates-from-significant-changes)
+- [Visits](#visits)
+- [Moving Off CLCircularRegion](#moving-off-clcircularregion)
+- [Choosing Accuracy](#choosing-accuracy)
+- [Simulating Position](#simulating-position)
+- [Info.plist Privacy Keys](#infoplist-privacy-keys)
+- [Pitfalls](#pitfalls)
 - [References](#references)
 
-## CLLocationUpdate.liveUpdates() (iOS 17+)
+## CLLocationUpdate.liveUpdates()
 
 ### Basic Usage
 
 ```swift
-func startReceivingLocation() async {
-    for try await update in CLLocationUpdate.liveUpdates() {
-        guard let location = update.location else { continue }
-        print("Lat: \(location.coordinate.latitude), Lon: \(location.coordinate.longitude)")
-        print("Accuracy: \(location.horizontalAccuracy)m")
+func logPositions() async throws {
+    for try await reading in CLLocationUpdate.liveUpdates() {
+        guard let here = reading.location else { continue }
+        let lat = here.coordinate.latitude
+        let lon = here.coordinate.longitude
+        let errorMetres = here.horizontalAccuracy
+        _ = (lat, lon, errorMetres)
     }
 }
 ```
 
 ### Full Implementation with Filtering
 
-Filter out stale, inaccurate, or duplicate updates to avoid unnecessary UI
-refreshes and reduce battery impact.
+Filtering keeps the UI from redrawing on noise and saves battery. Each rule
+below drops a sample that should never reach the screen.
 
 ```swift
+import CoreLocation
+import Observation
+
 @MainActor
 @Observable
-final class LocationService {
-    var currentLocation: CLLocation?
-    var isTracking = false
-
-    private var trackingTask: Task<Void, Never>?
-    private var lastReportedLocation: CLLocation?
-
-    /// Minimum distance in meters between reported locations.
-    private let distanceFilter: CLLocationDistance = 10
-    /// Maximum acceptable horizontal accuracy in meters.
-    private let accuracyThreshold: CLLocationAccuracy = 100
-    /// Maximum acceptable age for a delivered location.
-    private let maximumLocationAge: TimeInterval = 15
-
-    func startTracking() {
-        guard !isTracking else { return }
-        isTracking = true
-
-        trackingTask = Task {
+final class HikeLocator {
+    private(set) var position: CLLocation?
+    private(set) var isRunning = false
+    private var feed: Task<Void, Never>?
+    private var lastPublished: CLLocation?
+
+    private let minimumMove: CLLocationDistance = 10
+    private let worstAccuracy: CLLocationAccuracy = 100
+    private let oldestAge: TimeInterval = 15
+    private let fastestSpeed: CLLocationSpeed = 80
+
+    func start() {
+        guard !isRunning else { return }
+        isRunning = true
+        feed = Task {
             do {
-                let updates = CLLocationUpdate.liveUpdates(.default)
-
-                for try await update in updates {
+                for try await reading in CLLocationUpdate.liveUpdates(.default) {
                     if Task.isCancelled { break }
-
-                    // Skip updates without a location
-                    guard let location = update.location else { continue }
-
-                    // Skip inaccurate readings
-                    guard location.horizontalAccuracy >= 0,
-                          location.horizontalAccuracy < accuracyThreshold else {
-                        continue
-                    }
-
-                    // Skip stale readings
-                    guard abs(location.timestamp.timeIntervalSinceNow) < maximumLocationAge else {
-                        continue
-                    }
-
-                    // Skip impossible movement when speed/course are available
-                    if location.speed >= 0, location.speed > 80 {
-                        continue
-                    }
-                    if location.course >= 0, location.courseAccuracy < 0 {
-                        continue
-                    }
-
-                    // Skip if the user has not moved enough
-                    if let last = lastReportedLocation,
-                       location.distance(from: last) < distanceFilter {
-                        continue
-                    }
-
-                    lastReportedLocation = location
-                    currentLocation = location
+                    guard let fix = reading.location, accept(fix) else { continue }
+                    lastPublished = fix
+                    position = fix
                 }
             } catch is CancellationError {
-                // Expected when tracking stops.
             } catch {
-                currentLocation = nil
+                position = nil
             }
-
-            isTracking = false
+            isRunning = false
         }
     }
 
-    func stopTracking() {
-        trackingTask?.cancel()
-        trackingTask = nil
-        isTracking = false
+    func stop() {
+        feed?.cancel()
+        feed = nil
+        isRunning = false
+    }
+
+    private func accept(_ fix: CLLocation) -> Bool {
+        if fix.horizontalAccuracy < 0 || fix.horizontalAccuracy >= worstAccuracy { return false }
+        if abs(fix.timestamp.timeIntervalSinceNow) >= oldestAge { return false }
+        if fix.speed >= 0 && fix.speed > fastestSpeed { return false }
+        if fix.course >= 0 && fix.courseAccuracy < 0 { return false }
+        if let lastPublished, fix.distance(from: lastPublished) < minimumMove { return false }
+        return true
     }
 }
 ```
 
-### LiveConfiguration Options
-
-`CLLocationUpdate.liveUpdates(_:)` accepts a `LiveConfiguration` parameter:
-
-```swift
-// Default: balanced power and accuracy
-CLLocationUpdate.liveUpdates(.default)
+The rules: accuracy must be valid (not negative) and under 100 m; the sample
+must be younger than 15 s; a speed above 80 m/s is a glitch; a course without
+a valid course accuracy is ignored; moves under 10 m from the last published
+fix are not worth a redraw. `start()` refuses to run twice.
 
-// Best for navigation: highest accuracy, most frequent updates
-CLLocationUpdate.liveUpdates(.automotiveNavigation)
-
-// Fitness tracking
-CLLocationUpdate.liveUpdates(.fitness)
+### LiveConfiguration Options
 
-// Other-navigation (non-automotive)
-CLLocationUpdate.liveUpdates(.otherNavigation)
+`CLLocationUpdate.liveUpdates(_:)` takes a `LiveConfiguration`:
 
-// Airborne: for drone or aviation apps
-CLLocationUpdate.liveUpdates(.airborne)
-```
+| Value | Tuned for |
+|-------|-----------|
+| `.default` | balanced power and accuracy |
+| `.automotiveNavigation` | turn-by-turn driving, where precision and update rate matter most |
+| `.otherNavigation` | navigation that is not by car |
+| `.fitness` | workouts |
+| `.airborne` | drones and aviation |
 
-### Handling Diagnostics and Degraded Behavior (iOS 18+)
+### Diagnostics and Fallbacks (iOS 18+)
 
-Keep every `liveUpdates()` stream in an owned `Task` so the feature can cancel
-it when the map, route, or monitoring workflow stops. Treat diagnostics and bad
-location samples as state changes: update UI, fall back to cached/manual input,
-or suspend background work instead of continuing an invisible loop.
+Own every `liveUpdates()` stream in a stored `Task` and cancel it when the
+map, route or monitoring flow ends. Treat a diagnostic or a bad sample as a
+change of state: update the UI, fall back to cached or typed input, or pause
+background work. A loop that silently waits forever is the failure mode.
 
 ```swift
-for try await update in CLLocationUpdate.liveUpdates() {
-    // Check authorization status (iOS 18+)
-    if update.authorizationDenied {
-        // User denied location; prompt to open Settings
-        break
-    }
-
-    if update.authorizationDeniedGlobally {
-        // Location Services disabled system-wide
-        break
-    }
-
-    if update.insufficientlyInUse {
-        // App does not meet in-use requirements
-        continue
-    }
-
-    if update.locationUnavailable {
-        // Temporarily unable to determine location; keep iterating
-        continue
-    }
-
-    if update.stationary {
-        // Device stopped moving; updates will pause
-        continue
+@available(iOS 18, *)
+func watch(onDenied: @escaping @MainActor () -> Void) async throws {
+    for try await reading in CLLocationUpdate.liveUpdates() {
+        if reading.authorizationDenied {
+            await onDenied()
+            break
+        }
+        if reading.authorizationDeniedGlobally { break }
+        if reading.insufficientlyInUse { continue }
+        if reading.locationUnavailable { continue }
+        if reading.stationary { continue }
+        if let fix = reading.location { _ = fix }
     }
-
-    guard let location = update.location else { continue }
-    // Use location
 }
 ```
 
-Note: `authorizationDenied`, `authorizationDeniedGlobally`,
-`insufficientlyInUse`, `locationUnavailable`, and `stationary` are only
-available on iOS 18+. On iOS 17, check `update.location == nil` to detect
-unavailable location.
+| Diagnostic (iOS 18+) | Meaning | Response |
+|----------------------|---------|----------|
+| `authorizationDenied` | the user said no | stop location work, show a Settings path |
+| `authorizationDeniedGlobally` | Location Services are off for the device | explain the system switch |
+| `authorizationRestricted` | parental or MDM restriction | explain; no Settings fix for the user |
+| `insufficientlyInUse` | the app is not in a state that allows updates | pause; resume when the user returns to the feature |
+| `locationUnavailable` | temporarily cannot locate | keep iterating; let the user type a place or use the last known or visible area |
+| `accuracyLimited` | only approximate location | search a wider radius and size geofences generously; ask for precise location only when the user starts something that needs it |
+| `stationary` | device stopped moving; updates pause | nothing to do; they resume on movement |
 
-Map diagnostics to user-visible behavior instead of silently waiting:
+Availability: all of these are iOS 18 properties. On iOS 17 the only related
+property is `isStationary`, which iOS 18 deprecates in favour of
+`stationary`; detect unavailability on iOS 17 by `location == nil` on the update.
 
-- `authorizationDenied`: stop location work and show a Settings recovery path.
-- `authorizationDeniedGlobally`: explain that system Location Services are off.
-- `insufficientlyInUse`: suspend live updates until the feature is active again.
-- `locationUnavailable`: keep the feature usable with cached, typed, or map-region
-  input while waiting for recovery.
-- Reduced or approximate accuracy: widen search/geofence assumptions or request
-  full accuracy only from a user-triggered feature that needs it.
+Before publishing any fix, check that horizontal accuracy is valid, the
+timestamp is recent and the movement is plausible. `speed` and `course` are
+negative when unknown; read them only when non-negative.
 
-Before publishing a location, filter for valid horizontal accuracy, acceptable
-timestamp age, and plausible movement. Use `speed` and `course` only when their
-values are valid; negative values mean the measurement is unavailable.
+## Service Sessions (iOS 18+)
 
----
-
-## CLServiceSession (iOS 18+)
+`CLServiceSession` is iOS 18 and later, and unavailable on macOS.
 
 ### Setup and Lifecycle
 
-`CLServiceSession` declares your authorization requirements for a feature.
-Hold a strong reference for the session's entire duration.
+The session announces what a feature needs. Keep a strong reference for as
+long as the feature runs; dropping it tells the system you are done.
 
 ```swift
+@available(iOS 18, *)
 @MainActor
 @Observable
-final class LocationFeature {
-    private var serviceSession: CLServiceSession?
-    private var locationTask: Task<Void, Never>?
+final class NearbyFeature {
+    private var session: CLServiceSession?
+    private var feed: Task<Void, Never>?
+    private(set) var here: CLLocation?
 
     func activate() {
-        // Declare that this feature needs when-in-use authorization
-        serviceSession = CLServiceSession(authorization: .whenInUse)
-
-        locationTask = Task {
+        session = CLServiceSession(authorization: .whenInUse)
+        feed = Task {
             do {
-                for try await update in CLLocationUpdate.liveUpdates() {
-                    guard let location = update.location else { continue }
-                    // process location
+                for try await reading in CLLocationUpdate.liveUpdates() {
+                    if let fix = reading.location { here = fix }
                 }
             } catch is CancellationError {
-                // Expected when the feature stops.
             } catch {
-                // Show a degraded state or retry from user action.
+                here = nil
             }
         }
     }
 
     func deactivate() {
-        locationTask?.cancel()
-        locationTask = nil
-        // Release the session to signal you no longer need location
-        serviceSession = nil
+        feed?.cancel()
+        feed = nil
+        session = nil
     }
 }
 ```
 
+On an unexpected error, move to a degraded state and offer retry rather than
+leaving the screen spinning.
+
 ### Full Accuracy Request
 
-Request full accuracy when the user has granted approximate-only permission:
+When the user granted only approximate location, ask for precision for one
+feature:
 
 ```swift
-// Requires Info.plist:
-// NSLocationTemporaryUsageDescriptionDictionary
-//   NearbySearchPurpose: "Show nearby stores within walking distance."
-
-let session = CLServiceSession(
-    authorization: .whenInUse,
-    fullAccuracyPurposeKey: "NearbySearchPurpose"
-)
+@available(iOS 18, *)
+func preciseSession() -> CLServiceSession {
+    CLServiceSession(authorization: .whenInUse, fullAccuracyPurposeKey: "TrailNavigation")
+}
 ```
 
-### Always Authorization
-
-Only use `.always` when you need the system to relaunch your app in the
-background for significant location changes after termination.
+The key must exist in Info.plist under
+`NSLocationTemporaryUsageDescriptionDictionary`, mapped to a sentence the user
+will read.
 
-```swift
-let session = CLServiceSession(authorization: .always)
-```
+### Always Authorization
 
-Requires `NSLocationAlwaysAndWhenInUseUsageDescription` in Info.plist.
+`CLServiceSession(authorization: .always)` is for one case: the system must
+relaunch the app in the background after termination, for significant
+location changes. It requires `NSLocationAlwaysAndWhenInUseUsageDescription`.
 
 ### Implicit vs. Explicit Sessions
 
-On iOS 18+, `CLLocationUpdate.liveUpdates()` and `CLMonitor` create an
-implicit `CLServiceSession` behind the scenes if you do not create one. You
-need an explicit session when:
+If the app has no session, iOS 18 makes one on its behalf as soon as
+`liveUpdates()` or `CLMonitor` starts. Create one explicitly when:
 
-- You require `.always` authorization
-- You need full accuracy via `fullAccuracyPurposeKey`
-- You want to enforce explicit session management (add
-  `NSLocationRequireExplicitServiceSession` to Info.plist)
+- the feature needs `.always`;
+- the feature needs full accuracy through `fullAccuracyPurposeKey`;
+- Info.plist sets `NSLocationRequireExplicitServiceSession`, which turns
+  implicit sessions off.
 
----
+## Geofences with CLMonitor (iOS 17+)
 
-## CLMonitor for Geofencing (iOS 17+)
+`CLMonitor` is iOS 17 and macOS 14 and later; it is not available on watchOS,
+tvOS or visionOS.
 
 ### Basic Setup
 
-Use `CLMonitor` for modern condition monitoring. It is an `actor`, so its
-async APIs require `await`.
+`CLMonitor` is an `actor`, so every call is `await`ed. Create it with a name,
+add conditions, and read one `events` sequence.
 
 ```swift
+import CoreLocation
+
+struct Geofence: Sendable {
+    let id: String
+    let center: CLLocationCoordinate2D
+    let radius: CLLocationDistance
+}
+
 @available(iOS 17, *)
-actor GeofenceMonitor {
+actor ParkGates {
     private var monitor: CLMonitor?
-    private var monitoringTask: Task<Void, any Error>?
+    private var listener: Task<Void, any Error>?
 
-    func startMonitoring(regions: [GeofenceRegion]) async {
-        let monitor = await CLMonitor("myAppGeofences")
+    func start(_ fences: [Geofence], onChange: @escaping @Sendable (String, Bool) -> Void) async {
+        let monitor = await CLMonitor("park-gates")
         self.monitor = monitor
-
-        // Add circular geographic conditions
-        for region in regions {
-            let condition = CLMonitor.CircularGeographicCondition(
-                center: region.center,
-                radius: region.radius
-            )
-            await monitor.add(condition, identifier: region.id)
+        for fence in fences {
+            let area = CLMonitor.CircularGeographicCondition(center: fence.center, radius: fence.radius)
+            await monitor.add(area, identifier: fence.id)
         }
-
-        // Listen for events
-        monitoringTask = Task {
-            for try await event in await monitor.events {
-                switch event.state {
-                case .satisfied:
-                    // Device entered the region
-                    handleEntry(identifier: event.identifier)
-                case .unsatisfied:
-                    // Device exited the region
-                    handleExit(identifier: event.identifier)
-                case .unknown:
-                    break
-                default:
-                    break
+        listener = Task {
+            for try await change in await monitor.events {
+                switch change.state {
+                case .satisfied: onChange(change.identifier, true)
+                case .unsatisfied: onChange(change.identifier, false)
+                default: break
                 }
             }
         }
     }
 
-    func stopMonitoring() async {
-        monitoringTask?.cancel()
-        monitoringTask = nil
-
+    func stop() async {
+        listener?.cancel()
+        listener = nil
         if let monitor {
-            for identifier in await monitor.identifiers {
-                await monitor.remove(identifier)
+            for id in await monitor.identifiers {
+                await monitor.remove(id)
             }
         }
         monitor = nil
     }
-
-    private func handleEntry(identifier: String) {
-        print("Entered region: \(identifier)")
-    }
-
-    private func handleExit(identifier: String) {
-        print("Exited region: \(identifier)")
-    }
-}
-
-struct GeofenceRegion: Identifiable {
-    let id: String
-    let center: CLLocationCoordinate2D
-    let radius: CLLocationDistance
 }
 ```
 
-### Critical CLMonitor Rules
-
-1. **Maximum 20 conditions per app.** Adding more causes excess conditions
-   to report `unmonitored` state. This limit is per-app, not per-monitor.
+`.satisfied` means the device is inside (entry), `.unsatisfied` outside
+(exit); `.unknown` and anything else are ignored. `event.identifier` names the
+condition.
 
-2. **Do not recreate CLMonitor instances rapidly.** Creating a monitor with
-   the same name while one is still alive crashes the app. Reuse the instance
-   and call `add`/`remove` to change conditions.
-
-3. **Subscribe to `events` exactly once per CLMonitor.** Cancelling and
-   re-subscribing causes the new subscription to immediately cancel. Keep a
-   single long-lived subscription.
-
-4. **Use diffing for condition updates.** Instead of removing all conditions
-   and re-adding them, calculate which to add and which to remove.
+### Critical CLMonitor Rules
 
-5. **Target iOS 18+ for best results.** Pair `CLMonitor` with
-   `CLServiceSession` for reliable authorization management.
+- At most 20 conditions per app, counted across all monitors. Extra ones
+  report the `unmonitored` state.
+- Never recreate a monitor quickly. Creating one with the name of a live
+  monitor crashes the app. Keep one and call `add` and `remove`.
+- Subscribe to `events` once per monitor. Cancelling and subscribing again
+  gives a subscription that ends immediately; keep one long-lived listener.
+- Change conditions by diffing (add the new, remove the gone), not by
+  removing everything and adding it back.
+- Where possible, target iOS 18 and pair `CLMonitor` with a `CLServiceSession`
+  so authorization is handled reliably.
 
 ### Adding Conditions with Initial State
 
-Specify an assumed initial state to avoid spurious events on first add:
-
-```swift
-await monitor.add(condition, identifier: "office", assuming: .unsatisfied)
-```
-
-Use `.unsatisfied` when you believe the device is outside the region. Use
-`.satisfied` when you believe the device is inside.
+`add(_:identifier:assuming:)` supplies the state you believe is true, which
+avoids a spurious first event. Pass `.unsatisfied` when the device is
+believed outside, `.satisfied` when inside.
 
 ### Updating Conditions Dynamically
 
 ```swift
-func updateRegions(_ newRegions: [GeofenceRegion]) async {
-    guard let monitor else { return }
-
-    let existingIDs = Set(await monitor.identifiers)
-    let newIDs = Set(newRegions.map(\.id))
-
-    // Remove stale conditions
-    for id in existingIDs.subtracting(newIDs) {
-        await monitor.remove(id)
+@available(iOS 17, *)
+func sync(_ monitor: CLMonitor, to fences: [Geofence]) async {
+    let current = Set(await monitor.identifiers)
+    let wanted = Set(fences.map(\.id))
+    for gone in current.subtracting(wanted) {
+        await monitor.remove(gone)
     }
-
-    // Add new conditions
-    for region in newRegions where !existingIDs.contains(region.id) {
-        let condition = CLMonitor.CircularGeographicCondition(
-            center: region.center,
-            radius: region.radius
-        )
-        await monitor.add(condition, identifier: region.id, assuming: .unsatisfied)
+    for fence in fences where !current.contains(fence.id) {
+        let area = CLMonitor.CircularGeographicCondition(center: fence.center, radius: fence.radius)
+        await monitor.add(area, identifier: fence.id, assuming: .unsatisfied)
     }
 }
 ```
@@ -413,365 +324,300 @@ func updateRegions(_ newRegions: [GeofenceRegion]) async {
 ### Checking Last Known State
 
 ```swift
-if let record = await monitor.record(for: "office") {
-    let lastState = record.lastEvent.state
-    let lastDate = record.lastEvent.date
-    print("Region 'office' was \(lastState) at \(lastDate)")
+@available(iOS 17, *)
+func lastSeen(_ monitor: CLMonitor, fence id: String) async -> (CLMonitor.Event.State, Date)? {
+    let saved = await monitor.record(for: id)
+    guard let last = saved?.lastEvent else { return nil }
+    return (last.state, last.date)
 }
 ```
 
----
-
 ## CLBackgroundActivitySession
 
-Allow a when-in-use authorized app to receive location updates in the
-background. Requires the `Location updates` background mode capability.
+Available from iOS 17; not on macOS or tvOS. It lets an app with when-in-use
+authorization keep receiving location in the background. It needs the
+Location updates background mode, and while it is held the system shows the
+blue location indicator.
 
 ```swift
 @available(iOS 17, *)
-actor BackgroundLocationTracker {
-    private var backgroundSession: CLBackgroundActivitySession?
-    private var serviceSession: CLServiceSession?
-    private var trackingTask: Task<Void, Never>?
-
-    func startBackgroundTracking() {
-        // Declare authorization intent (iOS 18+)
-        serviceSession = CLServiceSession(authorization: .whenInUse)
-
-        // Start background activity session -- shows blue location indicator
-        backgroundSession = CLBackgroundActivitySession()
-
-        trackingTask = Task {
+actor WorkoutRecorder {
+    private var background: CLBackgroundActivitySession?
+    private var service: AnyObject?
+    private var feed: Task<Void, Never>?
+    private var trail: [CLLocation] = []
+
+    func begin() {
+        if #available(iOS 18, *) {
+            service = CLServiceSession(authorization: .whenInUse)
+        }
+        background = CLBackgroundActivitySession()
+        feed = Task {
             do {
-                for try await update in CLLocationUpdate.liveUpdates(.fitness) {
-                    guard let location = update.location else { continue }
-                    // Record location for fitness tracking, navigation, etc.
-                    await recordLocation(location)
+                for try await reading in CLLocationUpdate.liveUpdates(.fitness) {
+                    if let fix = reading.location { record(fix) }
                 }
-            } catch is CancellationError {
-                // Expected when background tracking stops.
-            } catch {
-                // Persist an error state or retry from user action.
-            }
+            } catch {}
         }
     }
 
-    func stopBackgroundTracking() {
-        trackingTask?.cancel()
-        trackingTask = nil
-        backgroundSession?.invalidate()
-        backgroundSession = nil
-        serviceSession = nil
+    private func record(_ fix: CLLocation) {
+        trail.append(fix)
     }
 
-    private func recordLocation(_ location: CLLocation) async {
-        // Persist to database, update Live Activity, etc.
+    func finish() {
+        feed?.cancel()
+        feed = nil
+        background?.invalidate()
+        background = nil
+        service = nil
     }
 }
 ```
 
 ### Background Requirements Summary
 
-To receive location in the background you need ALL of these:
-
-1. `Background Modes > Location updates` capability enabled.
-2. `NSLocationWhenInUseUsageDescription` in Info.plist.
-3. `.whenInUse` or `.always` authorization granted.
-4. Either a `CLBackgroundActivitySession` held or a Live Activity running.
-5. An active `CLLocationUpdate` or `CLMonitor` subscription.
+Background location works only when all of these hold:
 
-`.always` authorization is NOT required for background location. The
-difference: with `.always`, the system can relaunch your terminated app for
-significant location changes. With `.whenInUse` + background session, the
-app must be running (foreground or suspended).
+1. Background Modes > Location updates is enabled.
+2. Info.plist has `NSLocationWhenInUseUsageDescription`.
+3. The user granted `.whenInUse` or `.always`.
+4. The app holds a `CLBackgroundActivitySession`, or runs a Live Activity
+   (see `live-activities`).
+5. A `CLLocationUpdate` or `CLMonitor` subscription is active.
 
----
+`.always` is not needed for this. What `.always` adds is relaunch: after the
+app has been terminated, a significant move can bring it back. With
+`.whenInUse` plus a background session, the app must still be running,
+in the foreground or suspended.
 
-## Significant Location Change Monitoring
+## Coarse Updates from Significant Changes
 
-Use when you only need coarse location updates at ~500-meter intervals.
-Extremely battery efficient because it piggybacks on cellular tower changes.
+Coarse updates, roughly every 500 m, driven by cell tower changes and cheap on
+battery. There is no `CLLocationUpdate` equivalent, so this stays on
+`CLLocationManager`, which is legacy but valid:
 
 ```swift
-// Legacy CLLocationManager approach (still valid, no modern replacement)
-let manager = CLLocationManager()
-manager.startMonitoringSignificantLocationChanges()
-
-// The delegate receives updates when the device moves ~500m+ from the
-// last reported location. Updates arrive 1-5 minutes apart.
+let coarseManager = CLLocationManager()
+coarseManager.startMonitoringSignificantLocationChanges()
 ```
 
-There is no `CLLocationUpdate` equivalent for significant location changes.
-Use `CLLocationManager` for this specific use case.
-
----
+The delegate hears about moves of 500 m or more, typically 1 to 5 minutes
+apart.
 
-## Visit Monitoring
+## Visits
 
-Detect when the user arrives at or departs from a place. Useful for
-journaling, check-in, and context-aware features.
+Arrivals and departures at places, for journaling, check-ins or context-aware
+features.
 
 ```swift
-let manager = CLLocationManager()
-manager.startMonitoringVisits()
-
-// Delegate callback:
-func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
-    let coordinate = visit.coordinate
-    let arrivalDate = visit.arrivalDate
-    let departureDate = visit.departureDate
-    // departureDate == .distantFuture means the user is still at the location
+final class VisitLog: NSObject, CLLocationManagerDelegate {
+    private let manager = CLLocationManager()
+
+    func start() {
+        manager.delegate = self
+        manager.startMonitoringVisits()
+    }
+
+    func locationManager(_ manager: CLLocationManager, didVisit stop: CLVisit) {
+        let stillThere = stop.departureDate == .distantFuture
+        _ = (stop.coordinate, stop.arrivalDate, stillThere)
+    }
 }
 ```
 
----
+A `departureDate` of `.distantFuture` means the user has not left yet.
 
-## Region Monitoring Migration (CLCircularRegion to CLMonitor)
+## Moving Off CLCircularRegion
 
 ### Older Delegate Approach
 
 ```swift
-let region = CLCircularRegion(center: coordinate, radius: 200, identifier: "office")
-region.notifyOnEntry = true
-region.notifyOnExit = true
-manager.startMonitoring(for: region)
+let gate = CLCircularRegion(center: gateCenter, radius: 200, identifier: "north-gate")
+gate.notifyOnEntry = true
+gate.notifyOnExit = true
+legacyManager.startMonitoring(for: gate)
 ```
 
 ### Modern Approach (iOS 17+)
 
 ```swift
-// MODERN
-let monitor = await CLMonitor("appMonitor")
-let condition = CLMonitor.CircularGeographicCondition(center: coordinate, radius: 200)
-await monitor.add(condition, identifier: "office")
-
-for try await event in await monitor.events {
-    if event.identifier == "office" {
-        switch event.state {
-        case .satisfied: handleEntry()
-        case .unsatisfied: handleExit()
+@available(iOS 17, *)
+func watchGate(_ center: CLLocationCoordinate2D) async throws {
+    let monitor = await CLMonitor("gates")
+    await monitor.add(CLMonitor.CircularGeographicCondition(center: center, radius: 200),
+                      identifier: "north-gate")
+    for try await change in await monitor.events where change.identifier == "north-gate" {
+        switch change.state {
+        case .satisfied: break
+        case .unsatisfied: break
         default: break
         }
     }
 }
 ```
 
-Key differences:
-
-| Aspect | CLCircularRegion | CLMonitor |
-|--------|-----------------|-----------|
-| API style | Delegate callbacks | Async sequence |
-| Max regions | 20 per app | 20 per app |
-| Entry/exit | Separate booleans | State enum (satisfied/unsatisfied) |
-| Concurrency | @objc delegate | Actor-based |
-| Min iOS | iOS 7 | iOS 17 |
+| | `CLCircularRegion` | `CLMonitor` |
+|-|--------------------|-------------|
+| Shape of the API | callbacks on a delegate | an async sequence of events |
+| Region limit | 20 for the whole app | same 20, shared |
+| Entry and exit | two booleans | one state enum (satisfied, unsatisfied) |
+| Concurrency | `@objc` delegate | actor |
+| Minimum iOS | 7 | 17 |
 
----
-
-## Location Accuracy Management
+## Choosing Accuracy
 
 ### Accuracy Levels for CLLocationManager
 
-```swift
-manager.desiredAccuracy = kCLLocationAccuracyBest             // GPS, ~5m, highest power
-manager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters // ~10m
-manager.desiredAccuracy = kCLLocationAccuracyHundredMeters    // WiFi, ~100m
-manager.desiredAccuracy = kCLLocationAccuracyKilometer        // Cell tower, ~1km
-manager.desiredAccuracy = kCLLocationAccuracyThreeKilometers  // ~3km, lowest power
-manager.desiredAccuracy = kCLLocationAccuracyReduced          // ~5km, privacy-safe
-```
+Set with `manager.desiredAccuracy`:
 
-### Activity Type (Influences Power Management)
+| Constant | Roughly | Source and cost |
+|----------|---------|-----------------|
+| `kCLLocationAccuracyBest` | 5 m | GPS, most power |
+| `kCLLocationAccuracyNearestTenMeters` | 10 m | |
+| `kCLLocationAccuracyHundredMeters` | 100 m | Wi-Fi |
+| `kCLLocationAccuracyKilometer` | 1 km | cell towers |
+| `kCLLocationAccuracyThreeKilometers` | 3 km | least power |
+| `kCLLocationAccuracyReduced` | 5 km | approximate, privacy-preserving |
 
-```swift
-manager.activityType = .other                 // Default
-manager.activityType = .automotiveNavigation  // Highway speeds, high accuracy
-manager.activityType = .fitness               // Walking/running
-manager.activityType = .otherNavigation       // Boats, trains
-manager.activityType = .airborne              // Drones, aircraft (iOS 12+)
-```
+### Activity Type
 
-### CLLocationUpdate has no filtering
+`manager.activityType` guides power management:
 
-`CLLocationUpdate.liveUpdates()` does not support `desiredAccuracy` or
-`distanceFilter`. Filter the stream yourself:
+| Value | Use |
+|-------|-----|
+| `.other` | default |
+| `.automotiveNavigation` | highway speeds, high accuracy |
+| `.fitness` | walking and running |
+| `.otherNavigation` | boats, trains |
+| `.airborne` | drones and aircraft (iOS 12+) |
 
-```swift
-for try await update in CLLocationUpdate.liveUpdates() {
-    guard let location = update.location,
-          location.horizontalAccuracy < 50,
-          location.horizontalAccuracy >= 0 else { continue }
-    // Use filtered location
-}
-```
-
----
-
-## Testing Location in Simulator
-
-### Set a fixed simulated location
+### CLLocationUpdate has no filtering
 
-In Xcode: Debug > Simulate Location > choose a city or custom coordinate.
+`liveUpdates()` has neither `desiredAccuracy` nor `distanceFilter`. Pick a
+`LiveConfiguration` and filter the stream yourself, for example keep only
+fixes with `horizontalAccuracy >= 0 && horizontalAccuracy < 50`.
 
-### GPX File for a Moving Route
+## Simulating Position
 
-Create a `.gpx` file and add it to your Xcode project:
+- One fixed spot: Xcode Debug > Simulate Location, then a city or a custom
+  coordinate.
+- A moving path: add a `.gpx` file to the project and pick it under Edit
+  Scheme > Run > Options > Default Location.
 
 ```xml
 <?xml version="1.0"?>
-<gpx version="1.1" creator="Xcode">
-    <wpt lat="37.3349" lon="-122.0090">
-        <time>2025-01-01T00:00:00Z</time>
-        <name>Apple Park</name>
+<gpx creator="Xcode" version="1.1">
+    <wpt lat="47.6062" lon="-122.3321">
+        <name>Start</name>
+        <time>2026-01-01T09:00:00Z</time>
     </wpt>
-    <wpt lat="37.3318" lon="-122.0312">
-        <time>2025-01-01T00:01:00Z</time>
-        <name>Infinite Loop</name>
-    </wpt>
-    <wpt lat="37.3230" lon="-122.0322">
-        <time>2025-01-01T00:02:00Z</time>
-        <name>De Anza College</name>
+    <wpt lat="47.6097" lon="-122.3331">
+        <name>Market</name>
+        <time>2026-01-01T09:05:00Z</time>
     </wpt>
 </gpx>
 ```
 
-Set this file in the scheme: Edit Scheme > Run > Options > Default Location.
-
-The simulator interpolates between waypoints using timestamps. Playback loops
-automatically when it reaches the last waypoint.
+The simulator moves between waypoints at the pace their timestamps imply and
+starts over after the last one.
 
 ### Programmatic Simulation in Tests
 
-Use `CLLocationManager` with XCTest by injecting a location protocol:
+Unit tests need a position source they control. Hide the stream behind a
+protocol and inject a fake:
 
 ```swift
-protocol LocationProviding: Sendable {
-    func updates() -> AsyncStream<CLLocation>
+protocol PositionSource: Sendable {
+    func positions() -> AsyncStream<CLLocation>
 }
 
-// Production
-struct LiveLocationProvider: LocationProviding {
-    func updates() -> AsyncStream<CLLocation> {
+struct DevicePositionSource: PositionSource {
+    func positions() -> AsyncStream<CLLocation> {
         AsyncStream { continuation in
-            Task {
-                for try await update in CLLocationUpdate.liveUpdates() {
-                    if let location = update.location {
-                        continuation.yield(location)
+            let pump = Task {
+                do {
+                    for try await reading in CLLocationUpdate.liveUpdates() {
+                        if let fix = reading.location { continuation.yield(fix) }
                     }
-                }
+                } catch {}
                 continuation.finish()
             }
+            continuation.onTermination = { _ in pump.cancel() }
         }
     }
 }
 
-// Test mock
-struct MockLocationProvider: LocationProviding {
-    let locations: [CLLocation]
+struct ScriptedPositionSource: PositionSource {
+    let script: [CLLocation]
 
-    func updates() -> AsyncStream<CLLocation> {
+    func positions() -> AsyncStream<CLLocation> {
         AsyncStream { continuation in
-            for location in locations {
-                continuation.yield(location)
-            }
+            for fix in script { continuation.yield(fix) }
             continuation.finish()
         }
     }
 }
 ```
 
----
+The same seam works for code still on `CLLocationManager`: wrap the delegate
+behind the protocol and feed the scripted source in XCTest or Swift Testing.
 
-## Privacy and Info.plist Keys
+## Info.plist Privacy Keys
 
 ### Required Keys
 
-| Key | When to add |
-|-----|-------------|
-| `NSLocationWhenInUseUsageDescription` | Always, for any location use |
-| `NSLocationAlwaysAndWhenInUseUsageDescription` | Only if requesting `.always` |
+| Key | When |
+|-----|------|
+| `NSLocationWhenInUseUsageDescription` | every app that reads location at all |
+| `NSLocationAlwaysAndWhenInUseUsageDescription` | only when requesting `.always` |
 
 ### Optional Keys
 
-| Key | Purpose |
-|-----|---------|
-| `NSLocationTemporaryUsageDescriptionDictionary` | Per-feature full-accuracy descriptions |
-| `NSLocationRequireExplicitServiceSession` | Force explicit `CLServiceSession` usage (iOS 18+) |
-| `NSLocationDefaultAccuracyReduced` | Default to approximate location |
-| `UIBackgroundModes` (includes `location`) | Background location updates |
+| Key | Effect |
+|-----|--------|
+| `NSLocationTemporaryUsageDescriptionDictionary` | purpose strings for per-feature full accuracy |
+| `NSLocationRequireExplicitServiceSession` | disables implicit `CLServiceSession` (iOS 18+) |
+| `NSLocationDefaultAccuracyReduced` | the app starts with approximate location |
+| `UIBackgroundModes` containing `location` | background location updates |
 
 ### Usage Description Best Practices
 
-**Good:** "Shows nearby coffee shops within walking distance so you can find your next stop quickly."
+Say what the user gets. "Shows trailheads within a short drive of you" is a
+reason; "This app uses your location." is not, and App Review rejects vague
+purpose strings.
 
-**Bad:** "This app uses your location."
-
-App Review rejects vague usage descriptions. Be specific about what the user
-gains from sharing their location.
-
----
-
-## Common Pitfalls
+## Pitfalls
 
 ### CLMonitor crash on rapid recreation
 
-```swift
-// CRASH -- creating a monitor with a name already in use
-let monitorA = await CLMonitor("myMonitor")
-// ... immediately discard monitorA ...
-let monitorB = await CLMonitor("myMonitor") // NSInternalInconsistencyException
-```
-
-Fix: reuse the existing monitor instance. Only create a new one after the
-old one has been fully torn down (conditions removed, reference released,
-NOT in the same run loop).
+A second `CLMonitor` created with a name that is still in use raises
+`NSInternalInconsistencyException`. Reuse the monitor. Make a new one only
+after full teardown (conditions removed, reference released) and never in the
+same run loop turn.
 
-### Accuracy-limited updates need explicit handling
+### Approximate location arrives rarely
 
-Approximate location may update infrequently. On iOS 18+, check diagnostic
-properties such as `accuracyLimited` and `locationUnavailable`; otherwise,
-treat `update.location == nil` as a state change and provide a degraded
-experience instead of spinning or timing out.
+Approximate location can arrive rarely. On iOS 18 check `accuracyLimited` and
+`locationUnavailable`; on iOS 17 treat `location == nil` on the update as a state
+change. Either way, give a degraded experience instead of a spinner or a
+timeout.
 
 ### Forgetting to hold CLBackgroundActivitySession
 
-```swift
-// WRONG -- session is immediately deallocated
-func startBackground() {
-    let _ = CLBackgroundActivitySession()
-    // ^ No strong reference; session ends immediately
-}
-
-// CORRECT -- hold as a stored property
-private var bgSession: CLBackgroundActivitySession?
-
-func startBackground() {
-    bgSession = CLBackgroundActivitySession()
-}
-```
+`_ = CLBackgroundActivitySession()` deallocates at once and the session ends
+with it. Store it in a property.
 
 ### Not checking horizontalAccuracy
 
-```swift
-// WRONG -- using location with negative accuracy (invalid)
-guard let location = update.location else { continue }
-updateMap(location) // May have accuracy of -1 (invalid)
-
-// CORRECT
-guard let location = update.location,
-      location.horizontalAccuracy >= 0 else { continue }
-updateMap(location)
-```
-
-A `horizontalAccuracy` of -1 means the coordinate is invalid.
-
----
+A `horizontalAccuracy` of -1 marks the coordinate invalid. Check
+`horizontalAccuracy >= 0` before using any fix.
 
 ## References
 
-- Apple docs: [CLLocationUpdate](https://sosumi.ai/documentation/CoreLocation/CLLocationUpdate)
-- Apple docs: [CLServiceSession](https://sosumi.ai/documentation/CoreLocation/CLServiceSession)
-- Apple docs: [CLMonitor](https://sosumi.ai/documentation/CoreLocation/CLMonitor)
-- Apple docs: [CLBackgroundActivitySession](https://sosumi.ai/documentation/CoreLocation/CLBackgroundActivitySession)
-- Apple docs: [Requesting authorization](https://sosumi.ai/documentation/CoreLocation/requesting-authorization-to-use-location-services)
-- Apple docs: [Handling background location](https://sosumi.ai/documentation/CoreLocation/handling-location-updates-in-the-background)
+- [CLLocationUpdate](https://developer.apple.com/documentation/corelocation/cllocationupdate)
+- [CLServiceSession](https://developer.apple.com/documentation/corelocation/clservicesession)
+- [CLMonitor](https://developer.apple.com/documentation/corelocation/clmonitor)
+- [CLBackgroundActivitySession](https://developer.apple.com/documentation/corelocation/clbackgroundactivitysession)
+- [Location authorization](https://developer.apple.com/documentation/corelocation/requesting-authorization-to-use-location-services)
+- [Background location updates](https://developer.apple.com/documentation/corelocation/handling-location-updates-in-the-background)