HealthKit

Reading, writing, and querying health and fitness data on Apple platforms. The deep API reference — setup, every type category, all query types, workouts, activity rings, background delivery, the full SwiftUI manager, and version compatibility — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

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

1. ACCESS — read (consume existing data: steps, heart rate, sleep) · write (save your app's samples back to Health) · both. Each direction needs its own usage string and its own type set (typesToRead vs typesToWrite); requesting one does not grant the other.
2. QUERY_SHAPE — snapshot (HKSampleQuery/HKStatisticsQuery, one-time fetch) · time-series (HKStatisticsCollectionQuery, bucketed by interval) · live (HKObserverQuery + HKAnchoredObjectQuery, incremental updates and deletions). Live is the only shape that survives across launches and feeds background delivery.
3. BACKGROUND — none (foreground-only refresh) · enabled (enableBackgroundDelivery + observer query + the com.apple.developer.healthkit.background-delivery entitlement). Enabling background changes your entitlements, your query lifecycle, and your testing surface.

When to use

Building or reviewing any code that touches HKHealthStore — authorization, reading samples or statistics, writing quantity/category/workout samples, activity rings, or background delivery. Not for WorkoutKit scheduling (separate framework) or for ResearchKit surveys.

Core rules