How Protocol syncs, stores, and reconciles Steps

Why steps are different from every other metric

Oura and WHOOP are pulled. The server holds OAuth tokens and an hourly Vercel cron fetches their APIs whether or not the phone is awake. Apple Health has no cloud API at all. HealthKit is readable only on the device, by the app, while the app has runtime. So Apple Health steps are pushed: the iOS app reads HealthKit and POSTs a day summary to the web API, and the server's only lever is to ask the phone, politely, to do that.

WHOOP does not expose steps through its API. Its sync writes steps: null on every activity row, so for steps the real contest is Apple Health versus Oura.

Every trigger that syncs Apple Health steps

Six things cause the iOS app to read HealthKit and post. They share one endpoint and one per-day summary function; they differ in which days they read and how often they may fire.

Initial backfill: 365 days, in 15-day chunks

After the first HealthKit permission grant the app imports the trailing year, matching the 365-day window Oura and WHOOP get on connect. It runs behind the UI so onboarding proceeds immediately; the Today tab shows an “Importing…” card driven by HKSync.backfillProgress.

1. Reset or resume the cursorA per-user cursor in UserDefaults records how many of the oldest days are committed. If the target backfill version changed, the cursor resets to 0 and today's date is captured as a fixed anchor, so a resume on a later day maps every offset to the same calendar date.
2. Collect one windowOldest to newest, 15 days at a time. Each day is read via the shared summary(for:) function, which produces the full day payload (steps plus every other metric). Days with no HealthKit data are dropped.
3. Upload the window as a batchOne POST of { days: [...] }. Three attempts with 1 s, then 2 s backoff. If all three fail, the cursor stays put and the next launch resumes this exact window.
4. Persist the cursor, advanceOnly after a successful upload. Server upserts are idempotent, so a crash between upload and cursor write is safe. A background-task assertion holds ~30 s so a window in flight finishes when the user backgrounds the app.
5. Mark completeWhen the cursor reaches 365, the per-user version flag is set to the current backfill version and lastSyncedAt is stamped.

Ongoing sync: today plus a rolling window

After the backfill, two shapes of sync keep steps current.

The reason the rolling window exists is worth stating plainly: the server overwrites the Apple Health row for a day on each post. It does not keep the higher of the old and new value. So a day is correct only if it was read after it closed. Re-reading yesterday on the first sync of each morning is what makes yesterday's total trustworthy.

Foreground versus background

Silent push wake

An hourly Vercel cron at minute 20 finds Apple Health users whose data has gone stale and sends each device an invisible content-available push. The payload is exactly { "aps": { "content-available": 1 } }, with no alert, sound, or badge. Its only purpose is to hand the app runtime.

1. Select candidatesUsers with data_source_connections.source = 'apple_health' connected, a row in device_push_tokens, and last_synced_at at least 4 hours old. Oura-only and WHOOP-only devices are never woken; the cron already has their data.
2. Space the wakesAt least 4 hours between wakes per user, so at most six a day. iOS budgets background pushes and doesn't top the budget back up, so hourly knocking at an unresponsive device wastes what a better-timed wake could have used.
3. Back off the unreachableA wake is “unanswered” if no sync followed it. After 3 unanswered wakes the user drops to 24-hour spacing. The count self-heals: one successful sync moves last_synced_at past every prior wake and normal spacing resumes.
4. Send and logTokens are grouped by APNs environment (sandbox for debug builds, production for TestFlight and App Store). Dead tokens are pruned. One push_sends row per user records the campaign for the admin history.
5. Device respondsdidReceiveRemoteNotification checks HealthKit is available and authorized, runs syncToday() (which promotes to the rolling window if days rolled over), and returns .newData only if lastSyncedAt actually moved. iOS uses that verdict to decide how generously to wake the app in future, so the app reports honestly.

Push registration is deliberately decoupled from alert permission. The app registers for remote notifications even when the user declined alerts, because a device token is all a silent push needs. Declining a notification prompt should not cost someone their health sync.

How a day's step count is read

Every sync path calls the same summary(for: date) function. For steps it issues one HKStatisticsQuery on stepCount with .cumulativeSum, bounded to the calendar day in the device's current time zone.

// HKSync.summary(for:) — the steps read, simplified
let startOfDay = Calendar.current.startOfDay(for: date)
let endOfDay   = cal.date(byAdding: .day, value: 1, to: startOfDay)!
let dayPredicate = HKQuery.predicateForSamples(
    withStart: startOfDay, end: endOfDay, options: .strictStartDate)

async let steps = readSum(store, type: .init(.stepCount),
                          unit: .count(), predicate: dayPredicate)
// readSum → HKStatisticsQuery(options: .cumulativeSum)
//          sum > 0 ? sum : nil     // a zero day is sent as nil

• iPhone and Apple Watch are merged by HealthKit, not by Protocol. Because the query does not pass .separateBySource, HealthKit applies its own overlap resolution across the user's devices, and the sum matches the number the Health app shows. Protocol never sees per-device step samples and does not try to dedupe them itself.
• Third-party writers are included. Any app that writes stepCount samples to Health is part of the sum, exactly as the Health app would count them. There is no notOurs exclusion for steps; that predicate exists only for dietary and water reads, because Protocol writes meals and water back to Health.
• Day boundaries use .strictStartDate: a sample counts once, on the day it starts, so multi-day interval samples are never double-counted across days.
• Zero is never sent. A zero sum returns nil on device, and the server additionally ignores steps ≤ 0. A missing read looks like a sync gap, not a real zero.
• The date string is device-local. YYYY-MM-DD from Calendar.current. The server trusts it; it falls back to today in US Eastern only if the string is malformed.

Three layers, one unit: the day

Steps live in a per-source table, then in a merged daily row, and are finally re-checked at read time on the web dashboard. Nothing is stored at the sample level; the unit of storage is a day.

The wire payload

The iOS app posts either one day or a batch, authenticated with the user's Supabase JWT. The user is always the session user; there is no shared-secret mode.

// POST /api/sync/apple-health  (steps-relevant fields shown)
{
  "days": [
    { "date": "2026-09-02", "steps": 11842, "active_calories": 612, "basal_calories": 1710, ... },
    { "date": "2026-09-03", "steps": 3096,  "active_calories": 148, ... }
  ]
}

Per-source rows

One row per user, per day, per source. The Apple Health handler upserts with source = 'apple_health'; the Oura sync upserts the same shape with source = 'oura'. WHOOP writes rows too, always with null steps.

create table activity_records (
  id uuid primary key,
  user_id uuid not null references auth.users(id),
  date date not null,
  source text not null check (source in ('oura','apple_health','whoop','garmin','manual')),
  steps integer,
  active_calories integer,
  total_calories integer,
  active_minutes integer,
  water_oz numeric,
  score integer,
  raw_data jsonb,          -- { "method": "native_ios" } for Apple Health
  created_at, updated_at timestamptz,
  unique(user_id, date, source)
);
-- RLS: users own their rows. The ingest route writes with the service role.

The canonical day

After every day it writes, the ingest route calls updateDailyScorecard(userId, date). That function reads all of the day's source rows, applies the per-metric rules, and upserts one row on (user_id, date). Its steps column is what the web dashboard, iOS Today tab, rings, streaks, daily email, and coach all read. The route then recomputes weekly workout counts and per-metric streaks, and stamps data_source_connections.last_synced_at for apple_health, which is the timestamp the silent-wake cron and the stale banner watch.

Read-time freshness pass (web only)

getDashboardData re-reads today's activity_records and applies the same highest-value rule via pickHighestRecord. If a source row landed after the last scorecard merge, the dashboard shows it without waiting. It also derives activitySource, the label shown next to the step count. iOS does not re-resolve values; it displays the server-merged scorecard and mirrors the priority order only to pick the source label.

Which source wins for steps

Most metrics use a fixed priority list and take the first source with data. Sleep is Oura first; HRV is WHOOP first. Steps and active calories are the exception: the highest reported value wins. The reasoning is that a phone or watch that counted 12,000 steps has a more complete view than a ring that saw 8,000, and a source that reports zero almost always missed the day rather than observed stillness.

// lib/scorecard/updateScorecard.ts — the write-time rule
function pickHighest(records, field, prefKey, defaultOrder) {
  const nonZero = records.filter(r => Number(r[field] ?? 0) > 0);
  const pool = nonZero.length > 0 ? nonZero : records;
  if (prefs[prefKey]) return pick(pool, field, buildOrder(defaultOrder, prefKey));
  return max over pool[field];
}
steps = pickHighest(activities, 'steps', 'steps',
                    ['apple_health', 'garmin', 'whoop', 'oura']);

1. Drop zero rows when any source reported a real value.
2. If the user pinned a source for steps in Settings, revert to priority order with that source first. The default order (used only for the pin path and for tie labels) is Apple Health, then Garmin, WHOOP, Oura.
3. Otherwise take the maximum. Ties resolve to the earlier source in the default order.

The same rule runs in two places on purpose. The write-time merge makes the stored scorecard correct for iOS and email, which never re-derive. The read-time pass on web makes today feel live. Both are registered in the cross-platform parity doc (section 7, and the resolved drift item DR-3 from 2026-07-14, when the write-time side was brought into line with the dashboard).

Apple Health versus Oura versus WHOOP

For someone wearing an Apple Watch and an Oura ring, the practical outcome is: Apple Health usually wins because the phone plus watch see more of the day, Oura fills in when the app hasn't posted yet, and the number can go up when Apple's row finally lands but will not go down.

Known limits and gotchas

• Overwrite, not max, per source. Re-posting a day replaces the Apple Health row. A day read at 3:52 pm stays at its 3:52 pm count until something reads it after midnight. The rolling window and the rollover promotion exist to make that happen; a device that never gets runtime after a day closes will keep the partial count.
• Force-quit defeats everything background. iOS never delivers a silent push, and never fires an observer, for an app the user swiped away. Only opening the app recovers. The daily email's banner says so when a source is more than 24 hours stale (STALE_SYNC_HOURS).
• Observers are per-process. They are re-registered on every launch and lost on every termination. There is no signal to the server when they die; last_synced_at going stale is the only symptom.
• iOS budgets background pushes. A few an hour at most, dropped in Low Power Mode, deprioritized for rarely opened apps. The 4-hour spacing and the 24-hour backoff are there to spend that budget where it can work.
• Time zones are the device's. Steps are bucketed into the phone's current calendar day. A user who travels across zones can get a short or long “day”, and Oura's own local day may not line up exactly.
• Historical Oura rows can carry days Apple never posted. If Apple Health was connected later than Oura, days before the Apple backfill anchor are Oura-only and stay that way unless a version bump re-imports.
• Stale comments. /api/sync/all still says “Apple Health is push-only (iOS shortcut)”. The Shortcut path was removed in July 2026; the native app is the only ingest and JWT is the only auth.

Code map