@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/healthkit/references/healthkit-patterns.md

@@ -1,683 +1,529 @@
-# HealthKit Extended Patterns
+# HealthKit patterns
 
-Overflow reference for the `healthkit` skill. Contains advanced patterns that exceed the main skill file's scope.
+Extended examples that go with the main skill. Swift 6.3, iOS 26 unless noted.
 
 ## Contents
 
-- [Workout Session Lifecycle](#workout-session-lifecycle)
-- [Platform and Authorization Edge Cases](#platform-and-authorization-edge-cases)
-- [Background Delivery Details](#background-delivery-details)
-- [Anchored Object Queries](#anchored-object-queries)
-- [Predicate-Based Filtering](#predicate-based-filtering)
-- [Statistics Collection for Charts](#statistics-collection-for-charts)
-- [HealthKit + SwiftUI Integration](#healthkit--swiftui-integration)
-- [Characteristic Types](#characteristic-types)
+- [Workout sessions in depth](#workout-sessions-in-depth)
+- [Platform and authorization edge cases](#platform-and-authorization-edge-cases)
+- [Background delivery in detail](#background-delivery-in-detail)
+- [Anchored object queries](#anchored-object-queries)
+- [Predicates](#predicates)
+- [Chart data](#chart-data)
+- [SwiftUI integration](#swiftui-integration)
+- [Characteristics](#characteristics)
 
-## Workout Session Lifecycle
+## Workout sessions in depth
 
-`HKWorkoutSession` is available on iOS/iPadOS 17+, visionOS 1+, and watchOS
-2+. `HKLiveWorkoutBuilder` is available on iOS/iPadOS 26+ and watchOS 5+.
-When supporting iOS or iPadOS earlier than 26, gate live-builder code and use a
-non-live workout save path where appropriate.
+Availability repeats here because it drives the design: `HKWorkoutSession` is
+iOS and iPadOS 17+, visionOS 1+ and watchOS 2+, while `HKLiveWorkoutBuilder`
+is iOS and iPadOS 26+ and watchOS 5+. If the app still supports iOS or iPadOS
+before 26, gate the live builder and fall back to building and saving the
+workout after the fact instead of collecting it live.
 
-iPhone and iPad do not provide built-in live heart-rate samples. They require a
-paired external heart-rate sensor for live heart-rate collection, while Apple
-Watch workout sessions collect high-frequency heart-rate samples. iPhone also
-often locks during workouts; if the app shows health metrics on the Lock
-Screen, design around the system's workout-data access prompt and Live Activity
-surface.
+iPhone and iPad produce no live heart-rate samples by themselves; an external
+Bluetooth heart-rate sensor is needed. Phones also tend to lock partway through
+a workout, so if metrics should show on the Lock Screen, design around the
+system prompt that grants workout-data access there and around the Live
+Activity that displays it.
 
-### Full Workout Manager
+### A complete manager
 
 ```swift
 import HealthKit
+import Observation
 
+@available(iOS 26.0, *)
 @Observable
 @MainActor
-final class WorkoutManager: NSObject {
-    let healthStore = HKHealthStore()
-
+final class SwimTracker: NSObject {
+    private let store: HKHealthStore
     private var session: HKWorkoutSession?
     private var builder: HKLiveWorkoutBuilder?
 
-    var heartRate: Double = 0
-    var activeCalories: Double = 0
-    var distance: Double = 0
-    var elapsedTime: TimeInterval = 0
-    var isActive = false
-
-    func startWorkout(activityType: HKWorkoutActivityType) async throws {
-        let configuration = HKWorkoutConfiguration()
-        configuration.activityType = activityType
-        configuration.locationType = .outdoor
-
-        let session = try HKWorkoutSession(
-            healthStore: healthStore,
-            configuration: configuration
-        )
-        let builder = session.associatedWorkoutBuilder()
-
-        builder.dataSource = HKLiveWorkoutDataSource(
-            healthStore: healthStore,
-            workoutConfiguration: configuration
-        )
-
-        session.delegate = self
-        builder.delegate = self
-
-        self.session = session
-        self.builder = builder
+    private(set) var pulse: Double = 0
+    private(set) var kilocalories: Double = 0
+    private(set) var metres: Double = 0
+    private(set) var elapsed: TimeInterval = 0
+    private(set) var isRunning = false
 
-        session.startActivity(with: Date())
-        try await builder.beginCollection(at: Date())
-        isActive = true
+    init(store: HKHealthStore) {
+        self.store = store
     }
 
-    func pause() {
-        session?.pause()
+    func start() async throws {
+        let plan = HKWorkoutConfiguration()
+        plan.activityType = .swimming
+        plan.swimmingLocationType = .pool
+        plan.lapLength = HKQuantity(unit: .meter(), doubleValue: 25)
+
+        let newSession = try HKWorkoutSession(healthStore: store, configuration: plan)
+        let newBuilder = newSession.associatedWorkoutBuilder()
+        newSession.delegate = self
+        newBuilder.delegate = self
+        newBuilder.dataSource = HKLiveWorkoutDataSource(healthStore: store, workoutConfiguration: plan)
+        session = newSession
+        builder = newBuilder
+
+        let startDate = Date()
+        newSession.startActivity(with: startDate)
+        try await newBuilder.beginCollection(at: startDate)
     }
 
-    func resume() {
-        session?.resume()
+    func pause() { session?.pause() }
+    func resume() { session?.resume() }
+
+    func stop() async throws {
+        guard let activeSession = session, let activeBuilder = builder else { return }
+        activeSession.end()
+        try await activeBuilder.endCollection(at: .now)
+        _ = try await activeBuilder.finishWorkout()
+        session = nil
+        builder = nil
     }
 
-    func end() async throws {
-        guard let session, let builder else { return }
-        session.end()
-        try await builder.endCollection(at: Date())
-        try await builder.finishWorkout()
-        isActive = false
-        self.session = nil
-        self.builder = nil
+    fileprivate func apply(_ stats: HKStatistics, for type: HKQuantityType) {
+        switch type {
+        case HKQuantityType(.heartRate):
+            pulse = stats.mostRecentQuantity()?.doubleValue(for: .count().unitDivided(by: .minute())) ?? pulse
+        case HKQuantityType(.activeEnergyBurned):
+            kilocalories = stats.sumQuantity()?.doubleValue(for: .kilocalorie()) ?? kilocalories
+        case HKQuantityType(.distanceSwimming):
+            metres = stats.sumQuantity()?.doubleValue(for: .meter()) ?? metres
+        default:
+            break
+        }
     }
 }
 
-// MARK: - HKWorkoutSessionDelegate
-
-extension WorkoutManager: HKWorkoutSessionDelegate {
-    nonisolated func workoutSession(
-        _ workoutSession: HKWorkoutSession,
-        didChangeTo toState: HKWorkoutSessionState,
-        from fromState: HKWorkoutSessionState,
-        date: Date
-    ) {
+@available(iOS 26.0, *)
+extension SwimTracker: HKWorkoutSessionDelegate {
+    nonisolated func workoutSession(_ sender: HKWorkoutSession, didChangeTo toState: HKWorkoutSessionState,
+                                    from fromState: HKWorkoutSessionState, date: Date) {
         Task { @MainActor in
             switch toState {
-            case .running:
-                isActive = true
-            case .paused:
-                isActive = false
-            case .ended, .stopped:
-                isActive = false
-            default:
-                break
+            case .running: self.isRunning = true
+            case .paused, .ended, .stopped: self.isRunning = false
+            default: break
             }
         }
     }
 
-    nonisolated func workoutSession(
-        _ workoutSession: HKWorkoutSession,
-        didFailWithError error: Error
-    ) {
-        Task { @MainActor in
-            print("Workout session failed: \(error)")
-            isActive = false
-        }
+    nonisolated func workoutSession(_ sender: HKWorkoutSession, didFailWithError failure: Error) {
+        Task { @MainActor in self.isRunning = false }
     }
 }
 
-// MARK: - HKLiveWorkoutBuilderDelegate
-
-extension WorkoutManager: HKLiveWorkoutBuilderDelegate {
-    nonisolated func workoutBuilderDidCollectEvent(
-        _ workoutBuilder: HKLiveWorkoutBuilder
-    ) {
-        // Handle workout events (pause, resume, lap, etc.)
+@available(iOS 26.0, *)
+extension SwimTracker: HKLiveWorkoutBuilderDelegate {
+    nonisolated func workoutBuilderDidCollectEvent(_ workoutBuilder: HKLiveWorkoutBuilder) {
+        // Pause, resume and lap markers arrive here via workoutBuilder.workoutEvents.
     }
 
-    nonisolated func workoutBuilder(
-        _ workoutBuilder: HKLiveWorkoutBuilder,
-        didCollectDataOf collectedTypes: Set<HKSampleType>
-    ) {
+    nonisolated func workoutBuilder(_ workoutBuilder: HKLiveWorkoutBuilder, didCollectDataOf collectedTypes: Set<HKSampleType>) {
+        let time = workoutBuilder.elapsedTime
+        let snapshot = collectedTypes.compactMap { $0 as? HKQuantityType }
+            .compactMap { type in workoutBuilder.statistics(for: type).map { (type, $0) } }
         Task { @MainActor in
-            for type in collectedTypes {
-                guard let quantityType = type as? HKQuantityType else { continue }
+            self.elapsed = time
+            for (type, stats) in snapshot { self.apply(stats, for: type) }
+        }
+    }
+}
+```
 
-                let statistics = workoutBuilder.statistics(for: quantityType)
+Points to notice:
 
-                switch quantityType {
-                case HKQuantityType(.heartRate):
-                    heartRate = statistics?.mostRecentQuantity()?
-                        .doubleValue(for: HKUnit.count().unitDivided(by: .minute())) ?? 0
+- Both delegates are set: the session's for state changes and the builder's for
+  data.
+- `pause()` and `resume()` go through the session.
+- Ending runs `end()`, `endCollection(at:)`, `finishWorkout()` and then drops
+  the references.
+- Delegate callbacks are `nonisolated` and hop back with
+  `Task { @MainActor in ... }`. Session states to handle include `.running`,
+  `.paused`, `.ended` and `.stopped`.
+- In `didCollectDataOf`, cast each type to `HKQuantityType` and read
+  `statistics(for:)`: `mostRecentQuantity()` for heart rate in beats per
+  minute, `sumQuantity()` for energy in kilocalories and for distance in
+  metres. `elapsedTime` on the builder is the running clock.
 
-                case HKQuantityType(.activeEnergyBurned):
-                    activeCalories = statistics?.sumQuantity()?
-                        .doubleValue(for: .kilocalorie()) ?? 0
+### Mirroring a watch workout to iPhone
 
-                case HKQuantityType(.distanceWalkingRunning):
-                    distance = statistics?.sumQuantity()?
-                        .doubleValue(for: .meter()) ?? 0
+The watch runs the primary session and starts mirroring:
 
-                default:
-                    break
-                }
-            }
+```swift
+import HealthKit
 
-            elapsedTime = workoutBuilder.elapsedTime
-        }
-    }
+#if os(watchOS)
+func mirrorToPhone(_ primary: HKWorkoutSession) async throws {
+    try await primary.startMirroringToCompanionDevice()
 }
+#endif
 ```
 
-### Multi-Device Mirroring (watchOS + iOS)
-
-Start mirroring from the primary watchOS session. In the iOS companion app,
-assign `workoutSessionMirroringStartHandler` as the app launches so it can
-receive mirrored sessions even when launched in the background. The handler runs
-on an arbitrary background queue and may be called more than once if the devices
-disconnect and reconnect during a workout.
+The iPhone app registers its handler at launch, early enough that a mirrored
+session still arrives when the system launches the app in the background:
 
 ```swift
-// On watchOS: start mirroring to companion iPhone
-func startMirroring() async throws {
-    try await session?.startMirroringToCompanionDevice()
-}
+import HealthKit
 
-// On iOS: receive the mirrored session
-func setupMirroredSessionHandler() {
-    healthStore.workoutSessionMirroringStartHandler = { mirroredSession in
-        // mirroredSession is an HKWorkoutSession with type == .mirrored
-        mirroredSession.delegate = self
-        let builder = mirroredSession.associatedWorkoutBuilder()
-        builder.delegate = self
+@available(iOS 26.0, *)
+final class CompanionReceiver: NSObject, Sendable, HKWorkoutSessionDelegate, HKLiveWorkoutBuilderDelegate {
+    let store = HKHealthStore()
+
+    func install() {
+        store.workoutSessionMirroringStartHandler = { [weak self] mirrored in
+            guard let self, mirrored.type == .mirrored else { return }
+            mirrored.delegate = self
+            mirrored.associatedWorkoutBuilder().delegate = self
+        }
     }
-}
 
-// Send data between devices
-func sendDataToRemote(_ data: Data) async throws {
-    try await session?.sendToRemoteWorkoutSession(data: data)
+    func ping(_ session: HKWorkoutSession, payload: Data) async throws {
+        try await session.sendToRemoteWorkoutSession(data: payload)
+    }
+
+    func workoutSession(_ s: HKWorkoutSession, didChangeTo toState: HKWorkoutSessionState,
+                        from fromState: HKWorkoutSessionState, date: Date) {}
+    func workoutSession(_ s: HKWorkoutSession, didFailWithError failure: Error) {}
+    func workoutSession(_ s: HKWorkoutSession, didReceiveDataFromRemoteWorkoutSession data: [Data]) {}
+    func workoutBuilderDidCollectEvent(_ workoutBuilder: HKLiveWorkoutBuilder) {}
+    func workoutBuilder(_ workoutBuilder: HKLiveWorkoutBuilder, didCollectDataOf collectedTypes: Set<HKSampleType>) {}
 }
 ```
 
-## Platform and Authorization Edge Cases
-
-- Call `HKHealthStore.isHealthDataAvailable()` before any other HealthKit API.
-  Current Apple docs say Health data is available on iOS, watchOS, visionOS,
-  iPadOS 17+, and iOS apps running on Vision Pro. It is unavailable on iPadOS
-  16 or earlier and may be restricted by managed device policy.
-- Enabling the HealthKit capability for an iOS app can add `healthkit` to
-  `UIRequiredDeviceCapabilities`, preventing installation on unsupported
-  devices. Remove that entry only when HealthKit is optional and the app has a
-  useful non-HealthKit mode.
-- `authorizationStatus(for:)` is for write/share authorization. HealthKit does
-  not reveal whether read access was granted or denied. If read access is
-  denied, queries return samples your app saved successfully, which can look
-  like partial or empty data.
-- People can change HealthKit permissions later in Settings or the Health app.
-  Refresh permission-sensitive UI and write paths instead of assuming the
-  original authorization outcome still applies.
-- In Vision Pro Guest User sessions, previously authorized data may be readable,
-  but new authorization and writes can fail. Treat HealthKit writes as
-  best-effort unless the user explicitly initiated a save action that needs an
-  explanation.
-
-## Background Delivery Details
-
-Background delivery requires the HealthKit Background Delivery capability
-(`com.apple.developer.healthkit.background-delivery` on current Apple docs) and
-an executed `HKObserverQuery` for the same sample type. Set up observer queries
-when the app launches, then call `enableBackgroundDelivery` once; the system
-persists the registration.
+- The handler is called on an arbitrary background queue.
+- It can fire more than once, for example after the devices disconnect and
+  reconnect, so make it idempotent.
+- The session it receives is an ordinary `HKWorkoutSession` whose `type` is
+  `.mirrored`. Set the session delegate and the delegate of its
+  `associatedWorkoutBuilder()`.
+- Either side sends custom data with `sendToRemoteWorkoutSession(data:)`.
+
+## Platform and authorization edge cases
+
+- Turning on the capability can add `healthkit` to
+  `UIRequiredDeviceCapabilities`, which stops the app from installing on
+  devices without Health. Remove the entry only when HealthKit really is
+  optional and the app offers something useful without it.
+- People change permissions later in Settings or in the Health app. Re-check
+  before permission-dependent UI and write paths instead of trusting the answer
+  from the first request.
+- In a Guest User session on Apple Vision Pro, data the owner already allowed
+  may be readable while new authorization requests and writes fail. Treat
+  writes as best-effort there, unless the user explicitly asked to save, in
+  which case explain what happened.
+
+## Background delivery in detail
+
+- Entitlement: `com.apple.developer.healthkit.background-delivery`, added by
+  the HealthKit Background Delivery capability option.
+- An executed `HKObserverQuery` for the same sample type must exist.
+- `HKUpdateFrequency` is an upper bound, not a promise.
+- On iOS, step count is delivered at most hourly even if `.immediate` is
+  requested.
+- Background server queries do not run in Simulator.
+- If the completion handler is not called, HealthKit backs off and, after
+  repeated misses, may stop delivering.
 
 ```swift
-func configureHealthKitBackgroundDelivery() async throws {
-    let stepType = HKQuantityType(.stepCount)
+import HealthKit
 
-    let query = HKObserverQuery(
-        sampleType: stepType,
-        predicate: nil
-    ) { _, completionHandler, error in
+func startSleepSync(store: HKHealthStore, sync: @escaping @Sendable () async -> Void) async throws {
+    let sleep = HKCategoryType(.sleepAnalysis)
+    let observer = HKObserverQuery(sampleType: sleep, predicate: nil) { _, completionHandler, error in
         defer { completionHandler() }
-        guard error == nil else { return }
-        Task {
-            // Run an anchored query or statistics refresh here.
-        }
+        if error != nil { return }
+        Task { await sync() }
     }
-
-    healthStore.execute(query)
-
-    try await healthStore.enableBackgroundDelivery(
-        for: stepType,
-        frequency: .hourly
-    )
+    store.execute(observer)
+    try await store.enableBackgroundDelivery(for: sleep, frequency: .hourly)
 }
 ```
 
-Treat `HKUpdateFrequency` as a maximum delivery rate, not a guarantee. Some
-types have tighter system caps; for example, iOS step-count background delivery
-is capped at hourly even if `.immediate` is requested. Background server queries
-are not supported on Simulator, so validate delivery on real hardware. If the
-observer completion handler is not called, HealthKit backs off and can stop
-sending background updates after repeated failures.
+The `sync` closure is where an anchored query or a statistics refresh runs.
 
-## Anchored Object Queries
+## Anchored object queries
 
-Use `HKAnchoredObjectQuery` for incremental updates -- only fetches samples added or deleted since the last anchor.
+`HKAnchoredObjectQuery` returns only what changed (added or deleted) since the
+last `HKQueryAnchor`.
 
 ```swift
-@Observable
-final class StepTracker {
-    private let healthStore = HKHealthStore()
-    private var anchor: HKQueryAnchor?
-    private var observerQuery: HKObserverQuery?
+import HealthKit
+import Synchronization
 
-    var totalSteps: Double = 0
+final class GlucoseFeed: Sendable {
+    private let store: HKHealthStore
+    private let anchor = Mutex<HKQueryAnchor?>(nil)
 
-    func startMonitoring() {
-        let stepType = HKQuantityType(.stepCount)
+    init(store: HKHealthStore) { self.store = store }
 
-        // Initial fetch + ongoing updates
-        let anchoredQuery = HKAnchoredObjectQuery(
-            type: stepType,
+    func start(onChange: @escaping @Sendable ([HKSample], [HKDeletedObject]) -> Void) {
+        let query = HKAnchoredObjectQuery(
+            type: HKQuantityType(.bloodGlucose),
             predicate: nil,
-            anchor: anchor,
+            anchor: anchor.withLock { $0 },
             limit: HKObjectQueryNoLimit
-        ) { [weak self] query, added, deleted, newAnchor, error in
-            guard let self else { return }
-            self.anchor = newAnchor
-            self.processNewSamples(added ?? [])
+        ) { [weak self] _, added, removed, nextAnchor, _ in
+            self?.anchor.withLock { $0 = nextAnchor }
+            onChange(added ?? [], removed ?? [])
         }
-
-        // Enable updates handler for real-time monitoring
-        anchoredQuery.updateHandler = { [weak self] query, added, deleted, newAnchor, error in
-            guard let self else { return }
-            self.anchor = newAnchor
-            self.processNewSamples(added ?? [])
-        }
-
-        healthStore.execute(anchoredQuery)
-    }
-
-    private func processNewSamples(_ samples: [HKSample]) {
-        for sample in samples {
-            guard let quantitySample = sample as? HKQuantitySample else { continue }
-            let steps = quantitySample.quantity.doubleValue(for: .count())
-            totalSteps += steps
+        query.updateHandler = { [weak self] _, added, removed, nextAnchor, _ in
+            self?.anchor.withLock { $0 = nextAnchor }
+            onChange(added ?? [], removed ?? [])
         }
+        store.execute(query)
     }
 }
-```
 
-### Anchored Query with Async Descriptor
-
-```swift
-import HealthKit
-
-let stepType = HKQuantityType(.stepCount)
-let descriptor = HKAnchoredObjectQueryDescriptor(
-    predicates: [.quantitySample(type: stepType)],
-    anchor: savedAnchor
-)
-
-// One-shot
-let result = try await descriptor.result(for: healthStore)
-let newSamples = result.addedSamples
-let deletedObjects = result.deletedObjects
-let newAnchor = result.newAnchor
-
-// Long-running with updates
-for try await result in descriptor.results(for: healthStore) {
-    // Process result.addedSamples and result.deletedObjects
+func glucoseChanges(since mark: HKQueryAnchor?, store: HKHealthStore) async throws -> HKQueryAnchor {
+    let query = HKAnchoredObjectQueryDescriptor(
+        predicates: [.quantitySample(type: HKQuantityType(.bloodGlucose))],
+        anchor: mark
+    )
+    let delta = try await query.result(for: store)
+    _ = (delta.addedSamples, delta.deletedObjects)
+    return delta.newAnchor
 }
 ```
 
-## Predicate-Based Filtering
+The first handler delivers the initial batch; `updateHandler` keeps delivering
+changes. Both run on a background queue, so the saved anchor sits behind a
+`Mutex`. With the descriptor, `result(for:)` returns `addedSamples`,
+`deletedObjects` and `newAnchor`, and `results(for:)` streams further updates.
 
-### Time-Based Predicates
+## Predicates
 
 ```swift
-// Samples from today
-let today = Calendar.current.startOfDay(for: Date())
-let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: today)!
-let todayPredicate = HKQuery.predicateForSamples(
-    withStart: today, end: tomorrow
-)
-
-// Samples from the last 7 days
-let oneWeekAgo = Calendar.current.date(byAdding: .day, value: -7, to: Date())!
-let weekPredicate = HKQuery.predicateForSamples(
-    withStart: oneWeekAgo, end: Date()
-)
-
-// Strict: sample must be entirely within the range
-let strictPredicate = HKQuery.predicateForSamples(
-    withStart: today, end: tomorrow,
-    options: .strictStartDate
-)
-```
+import Foundation
+import HealthKit
 
-### Source-Based Predicates
+func predicates() -> NSPredicate? {
+    let now = Date()
+    let calendar = Calendar.current
+    let todayStart = calendar.startOfDay(for: now)
+    guard let weekAgo = calendar.date(byAdding: .day, value: -7, to: now) else { return nil }
 
-```swift
-// Only samples from the current app
-let sourcePredicate = HKQuery.predicateForObjects(
-    from: HKSource.default()
-)
-
-// Only samples from Apple Watch
-let devicePredicate = HKQuery.predicateForObjects(
-    withDeviceProperty: HKDevicePropertyKeyModel,
-    allowedValues: ["Watch"]
-)
-```
+    let today = HKQuery.predicateForSamples(withStart: todayStart, end: now)
+    let lastWeek = HKQuery.predicateForSamples(withStart: weekAgo, end: now)
+    let startsInWeek = HKQuery.predicateForSamples(withStart: weekAgo, end: now, options: .strictStartDate)
+    let mine = HKQuery.predicateForObjects(from: HKSource.default())
+    let fromWatch = HKQuery.predicateForObjects(withDeviceProperty: HKDevicePropertyKeyModel, allowedValues: ["Watch"])
 
-### Compound Predicates
+    _ = (today, lastWeek)
+    return NSCompoundPredicate(andPredicateWithSubpredicates: [startsInWeek, mine, fromWatch])
+}
 
-```swift
-let todayFromWatch = NSCompoundPredicate(
-    andPredicateWithSubpredicates: [todayPredicate, devicePredicate]
-)
-
-let descriptor = HKSampleQueryDescriptor(
-    predicates: [.quantitySample(type: stepType, predicate: todayFromWatch)],
-    sortDescriptors: [SortDescriptor(\.endDate, order: .reverse)]
-)
+func watchStepsThisWeek(_ filter: NSPredicate) -> HKSampleQueryDescriptor<HKQuantitySample> {
+    HKSampleQueryDescriptor(
+        predicates: [.quantitySample(type: HKQuantityType(.stepCount), predicate: filter)],
+        sortDescriptors: []
+    )
+}
 ```
 
-## Statistics Collection for Charts
+- `predicateForSamples(withStart:end:)` filters by time range.
+- Adding `options: .strictStartDate` keeps only samples whose start date falls
+  inside the range.
+- `predicateForObjects(from: HKSource.default())` keeps this app's own samples.
+- `predicateForObjects(withDeviceProperty:allowedValues:)` filters by device,
+  here the model `"Watch"`.
+- `NSCompoundPredicate(andPredicateWithSubpredicates:)` combines them before
+  they go into `.quantitySample(type:predicate:)`.
 
-### Weekly Step Count Chart Data
+## Chart data
 
 ```swift
-struct DailyStepData: Identifiable {
-    let id = UUID()
-    let date: Date
-    let steps: Double
+import HealthKit
+
+struct DayTotal: Identifiable {
+    let day: Date
+    let value: Double
+    var id: Date { day }
 }
 
-func fetchWeeklyStepData() async throws -> [DailyStepData] {
+func lastSevenDaysOfSteps(_ store: HKHealthStore) async throws -> [DayTotal] {
     let calendar = Calendar.current
-    let today = calendar.startOfDay(for: Date())
-    let endDate = calendar.date(byAdding: .day, value: 1, to: today)!
-    let startDate = calendar.date(byAdding: .day, value: -7, to: endDate)!
-
-    let stepType = HKQuantityType(.stepCount)
-    let predicate = HKQuery.predicateForSamples(
-        withStart: startDate, end: endDate
-    )
-    let samplePredicate = HKSamplePredicate.quantitySample(
-        type: stepType, predicate: predicate
-    )
-
+    guard let end = calendar.date(byAdding: .day, value: 1, to: calendar.startOfDay(for: .now)),
+          let start = calendar.date(byAdding: .day, value: -7, to: end) else { return [] }
     let query = HKStatisticsCollectionQueryDescriptor(
-        predicate: samplePredicate,
+        predicate: .quantitySample(type: HKQuantityType(.stepCount),
+                                   predicate: HKQuery.predicateForSamples(withStart: start, end: end)),
         options: .cumulativeSum,
-        anchorDate: endDate,
+        anchorDate: end,
         intervalComponents: DateComponents(day: 1)
     )
-
-    let collection = try await query.result(for: healthStore)
-
-    var data: [DailyStepData] = []
-    collection.statisticsCollection.enumerateStatistics(
-        from: startDate, to: endDate
-    ) { statistics, _ in
-        let steps = statistics.sumQuantity()?
-            .doubleValue(for: .count()) ?? 0
-        data.append(DailyStepData(date: statistics.startDate, steps: steps))
+    var totals: [DayTotal] = []
+    try await query.result(for: store).enumerateStatistics(from: start, to: end) { stats, _ in
+        totals.append(DayTotal(day: stats.startDate, value: stats.sumQuantity()?.doubleValue(for: .count()) ?? 0))
     }
-
-    return data
+    return totals
 }
-```
-
-### Hourly Heart Rate Averages
-
-```swift
-func fetchHourlyHeartRate(for date: Date) async throws -> [(hour: Date, bpm: Double)] {
-    let calendar = Calendar.current
-    let startOfDay = calendar.startOfDay(for: date)
-    let endOfDay = calendar.date(byAdding: .day, value: 1, to: startOfDay)!
-
-    let heartRateType = HKQuantityType(.heartRate)
-    let predicate = HKQuery.predicateForSamples(
-        withStart: startOfDay, end: endOfDay
-    )
-    let samplePredicate = HKSamplePredicate.quantitySample(
-        type: heartRateType, predicate: predicate
-    )
 
+func hourlyPulse(_ store: HKHealthStore, on day: Date) async throws -> [DayTotal] {
+    let start = Calendar.current.startOfDay(for: day)
+    let end = start.addingTimeInterval(24 * 3_600)
     let query = HKStatisticsCollectionQueryDescriptor(
-        predicate: samplePredicate,
+        predicate: .quantitySample(type: HKQuantityType(.heartRate),
+                                   predicate: HKQuery.predicateForSamples(withStart: start, end: end)),
         options: .discreteAverage,
-        anchorDate: endOfDay,
+        anchorDate: start,
         intervalComponents: DateComponents(hour: 1)
     )
-
-    let collection = try await query.result(for: healthStore)
-    let unit = HKUnit.count().unitDivided(by: .minute())
-
-    var hourlyData: [(hour: Date, bpm: Double)] = []
-    collection.statisticsCollection.enumerateStatistics(
-        from: startOfDay, to: endOfDay
-    ) { statistics, _ in
-        if let avg = statistics.averageQuantity()?.doubleValue(for: unit) {
-            hourlyData.append((hour: statistics.startDate, bpm: avg))
+    let bpm = HKUnit.count().unitDivided(by: .minute())
+    var points: [DayTotal] = []
+    try await query.result(for: store).enumerateStatistics(from: start, to: end) { stats, _ in
+        if let average = stats.averageQuantity()?.doubleValue(for: bpm) {
+            points.append(DayTotal(day: stats.startDate, value: average))
         }
     }
-
-    return hourlyData
+    return points
 }
 ```
 
-## HealthKit + SwiftUI Integration
+The weekly chart covers the seven days ending at the start of tomorrow and
+anchors on that end date. The hourly chart uses `.discreteAverage` and adds a
+point only for hours that have data.
 
-### HealthKit Manager with `@Observable`
+## SwiftUI integration
 
 ```swift
 import HealthKit
+import Observation
 import SwiftUI
 
 @Observable
 @MainActor
-final class HealthManager {
-    let healthStore = HKHealthStore()
-
-    var isAuthorized = false
-    var todaySteps: Double = 0
-    var recentHeartRate: Double = 0
-
-    var isAvailable: Bool {
-        HKHealthStore.isHealthDataAvailable()
-    }
-
-    func requestAuthorization() async throws {
-        let typesToRead: Set<HKObjectType> = [
-            HKQuantityType(.stepCount),
-            HKQuantityType(.heartRate)
-        ]
-
-        try await healthStore.requestAuthorization(
-            toShare: [],
-            read: typesToRead
-        )
-        isAuthorized = true
+final class VitalsModel {
+    private let store = HKHealthStore()
+    var isAvailable: Bool { HKHealthStore.isHealthDataAvailable() }
+    private(set) var isAuthorized = false
+    private(set) var steps: Double = 0
+    private(set) var restingPulse: Double?
+
+    func authorize() async {
+        do {
+            try await store.requestAuthorization(toShare: [], read: [
+                HKQuantityType(.stepCount), HKQuantityType(.restingHeartRate)
+            ])
+            isAuthorized = true
+        } catch {
+            isAuthorized = false
+        }
     }
 
-    func refreshData() async {
-        async let steps = fetchTodaySteps()
-        async let heartRate = fetchLatestHeartRate()
-
-        todaySteps = (try? await steps) ?? 0
-        recentHeartRate = (try? await heartRate) ?? 0
+    func refresh() async {
+        async let stepTotal = todaysSteps()
+        async let pulse = latestRestingPulse()
+        steps = (try? await stepTotal) ?? 0
+        restingPulse = try? await pulse
     }
 
-    private func fetchTodaySteps() async throws -> Double {
-        let calendar = Calendar.current
-        let startOfDay = calendar.startOfDay(for: Date())
-        let predicate = HKQuery.predicateForSamples(
-            withStart: startOfDay, end: Date()
-        )
-        let stepType = HKQuantityType(.stepCount)
-        let samplePredicate = HKSamplePredicate.quantitySample(
-            type: stepType, predicate: predicate
-        )
+    private func todaysSteps() async throws -> Double {
+        let start = Calendar.current.startOfDay(for: .now)
         let query = HKStatisticsQueryDescriptor(
-            predicate: samplePredicate, options: .cumulativeSum
+            predicate: .quantitySample(type: HKQuantityType(.stepCount),
+                                       predicate: HKQuery.predicateForSamples(withStart: start, end: .now)),
+            options: .cumulativeSum
         )
-        return try await query.result(for: healthStore)?
-            .sumQuantity()?.doubleValue(for: .count()) ?? 0
+        return try await query.result(for: store)?.sumQuantity()?.doubleValue(for: .count()) ?? 0
     }
 
-    private func fetchLatestHeartRate() async throws -> Double {
-        let heartRateType = HKQuantityType(.heartRate)
-        let descriptor = HKSampleQueryDescriptor(
-            predicates: [.quantitySample(type: heartRateType)],
+    private func latestRestingPulse() async throws -> Double? {
+        let query = HKSampleQueryDescriptor(
+            predicates: [.quantitySample(type: HKQuantityType(.restingHeartRate))],
             sortDescriptors: [SortDescriptor(\.endDate, order: .reverse)],
             limit: 1
         )
-        let results = try await descriptor.result(for: healthStore)
-        let unit = HKUnit.count().unitDivided(by: .minute())
-        return results.first?.quantity.doubleValue(for: unit) ?? 0
+        return try await query.result(for: store).first?.quantity
+            .doubleValue(for: .count().unitDivided(by: .minute()))
     }
 }
-```
 
-### SwiftUI View with HealthKit
-
-```swift
-struct HealthDashboardView: View {
-    @Environment(HealthManager.self) private var healthManager
+struct VitalsScreen: View {
+    @Environment(VitalsModel.self) private var model
 
     var body: some View {
-        NavigationStack {
-            Group {
-                if !healthManager.isAvailable {
-                    ContentUnavailableView(
-                        "HealthKit Unavailable",
-                        systemImage: "heart.slash",
-                        description: Text("This device does not support HealthKit.")
-                    )
-                } else if !healthManager.isAuthorized {
-                    authorizationPrompt
-                } else {
-                    healthDataView
-                }
-            }
-            .navigationTitle("Health")
-        }
-    }
-
-    private var authorizationPrompt: some View {
-        ContentUnavailableView {
-            Label("Health Access", systemImage: "heart.text.square")
-        } description: {
-            Text("Grant access to view your health data.")
-        } actions: {
-            Button("Authorize") {
-                Task {
-                    try? await healthManager.requestAuthorization()
-                }
+        if !model.isAvailable {
+            ContentUnavailableView("Health data unavailable", systemImage: "heart.slash")
+        } else if !model.isAuthorized {
+            ContentUnavailableView {
+                Label("Connect to Health", systemImage: "heart.text.square")
+            } actions: {
+                Button("Allow access") { Task { await model.authorize() } }
             }
-            .buttonStyle(.borderedProminent)
-        }
-    }
-
-    private var healthDataView: some View {
-        List {
-            Section("Today") {
-                LabeledContent("Steps") {
-                    Text(healthManager.todaySteps, format: .number.precision(.fractionLength(0)))
-                }
-                LabeledContent("Heart Rate") {
-                    Text("\(Int(healthManager.recentHeartRate)) bpm")
-                }
+        } else {
+            List {
+                LabeledContent("Steps today", value: model.steps, format: .number)
+                LabeledContent("Resting pulse", value: model.restingPulse.map { "\(Int($0)) bpm" } ?? "-")
             }
-        }
-        .task {
-            await healthManager.refreshData()
-        }
-        .refreshable {
-            await healthManager.refreshData()
+            .task { await model.refresh() }
+            .refreshable { await model.refresh() }
         }
     }
 }
-```
 
-### App Entry Point Wiring
-
-```swift
-@main
-struct MyHealthApp: App {
-    @State private var healthManager = HealthManager()
+struct VitalsApp: App {
+    @State private var model = VitalsModel()
 
     var body: some Scene {
         WindowGroup {
-            HealthDashboardView()
-                .environment(healthManager)
+            VitalsScreen().environment(model)
         }
     }
 }
 ```
 
-## Characteristic Types
+- The model requests read-only access by passing an empty `toShare` set.
+- `refresh()` runs both fetches at once with `async let`.
+- The latest value comes from a sample descriptor with `limit: 1` sorted by end
+  date, newest first.
+- The screen checks availability first, then authorization, then shows the
+  data. `isAuthorized` becomes `true` once `requestAuthorization` returns
+  without throwing, which only means the sheet was handled, not that reads were
+  allowed.
+- The app creates the model as `@State` and injects it with `.environment`.
 
-Characteristic types are read-only values set by the user in the Health app. They do not require sample queries.
+## Characteristics
+
+Characteristics are values the user enters once in Health, such as blood type.
+They are read directly; no query is involved, and all of these calls throw.
 
 ```swift
-func readCharacteristics() throws {
-    // Date of birth
-    let dobComponents = try healthStore.dateOfBirthComponents()
-    let calendar = Calendar.current
-    if let dob = calendar.date(from: dobComponents) {
-        let age = calendar.dateComponents([.year], from: dob, to: Date()).year ?? 0
-        print("Age: \(age)")
-    }
+import HealthKit
 
-    // Biological sex
-    let biologicalSex = try healthStore.biologicalSex().biologicalSex
-    switch biologicalSex {
-    case .female: print("Female")
-    case .male: print("Male")
-    case .other: print("Other")
-    case .notSet: print("Not set")
-    @unknown default: break
-    }
+struct Profile {
+    var age: Int?
+    var sex: HKBiologicalSex = .notSet
+    var blood: HKBloodType = .notSet
+    var skin: HKFitzpatrickSkinType = .notSet
+    var wheelchair: HKWheelchairUse = .notSet
+}
 
-    // Blood type
-    let bloodType = try healthStore.bloodType().bloodType
-    switch bloodType {
-    case .aPositive: print("A+")
-    case .aNegative: print("A-")
-    case .bPositive: print("B+")
-    case .bNegative: print("B-")
-    case .abPositive: print("AB+")
-    case .abNegative: print("AB-")
-    case .oPositive: print("O+")
-    case .oNegative: print("O-")
-    case .notSet: print("Not set")
-    @unknown default: break
+func loadProfile(_ store: HKHealthStore) -> Profile {
+    var profile = Profile()
+    do {
+        let born = try store.dateOfBirthComponents()
+        if let birthday = Calendar.current.date(from: born) {
+            profile.age = Calendar.current.dateComponents([.year], from: birthday, to: .now).year
+        }
+    } catch let error as HKError where error.code == .errorNoData {
+        profile.age = nil
+    } catch {
+        profile.age = nil
     }
-
-    // Fitzpatrick skin type
-    let skinType = try healthStore.fitzpatrickSkinType().skinType
-    print("Skin type: \(skinType.rawValue)")
-
-    // Wheelchair use
-    let wheelchair = try healthStore.wheelchairUse().wheelchairUse
-    print("Wheelchair: \(wheelchair == .yes)")
+    profile.sex = (try? store.biologicalSex().biologicalSex) ?? .notSet
+    profile.blood = (try? store.bloodType().bloodType) ?? .notSet
+    profile.skin = (try? store.fitzpatrickSkinType().skinType) ?? .notSet
+    profile.wheelchair = (try? store.wheelchairUse().wheelchairUse) ?? .notSet
+    return profile
 }
 ```
 
-**Important:** These throw an error if the value is not set, so always use `try` and handle the `HKError.errorNoData` case.
+| Type | Cases |
+|---|---|
+| `HKBiologicalSex` | `.female`, `.male`, `.other`, `.notSet` |
+| `HKBloodType` | `.aPositive`, `.aNegative`, `.bPositive`, `.bNegative`, `.abPositive`, `.abNegative`, `.oPositive`, `.oNegative`, `.notSet` |
 
-```swift
-do {
-    let dob = try healthStore.dateOfBirthComponents()
-    // Use dob
-} catch let error as HKError where error.code == .errorNoData {
-    // User hasn't set date of birth in Health app
-} catch {
-    // Other error
-}
-```
+An unset value throws `HKError` with code `.errorNoData`; catch that case
+separately from real failures.