[BEAR-6800]: (Time Asleep Syncing) Return sleep phases and add a configurable cut-off hour

[natbearable]

Jira

BEAR-6800 — Update apple health package to return sleep stages

Description

The native bucketed sleep query now returns per-night sleep phases for sources that emit them — Apple Watch on iOS 16+. Each phase comes through as a raw window with its own start and end time, slotted under entry.sleepTimes.phases in the existing bucketed sleep response. Phases are labelled light (Apple's Core), deep, rem, and awake, so mid-night wake-ups show up alongside the sleep stages.

A new sleepCutOffHour option was also added to readBucketedSleep. Samples at or past this hour roll forward into the next day's bucket, and the option defaults to 12 (noon) so daytime naps and the following night both land where you'd expect. Callers can pass any hour 0-23 to override — e.g. 19 to restore the previous 7pm rule.

Why this approach: The cut-off was previously inferred from the caller's startTime hour, which made the contract implicit and easy to get wrong on the JS side. An explicit option makes it obvious what's happening and gives the mobile app a one-line kill switch back to 7pm via remote config if 12pm causes problems. Phases are pulled at the same point where the source is picked, so we only emit phases from the source whose totals we're already using — keeping the data internally consistent with the asleep duration.

Acceptance criteria

• Sleep cutoff is configurable via sleepCutOffHour, defaulting to 12pm
• Naps are included in time asleep (every asleep sample's duration is summed regardless of when it occurred)
• Phase data is returned for each night when the source provides it

Screenshots / Recordings

Screen.Recording.2026-06-25.at.17.40.38.mov

Quality

Have you done the following?

• Reviewed my own PR
• Handled returned failures or exceptions
• Checked that no sensitive data is exposed
• Checked typos

• Yes
• N/A

Jira

Have you done the following?

• Added user testing steps
• Added a 🟢-SAFE-TO-RELEASE or 🔴-NOT-SAFE-TO-RELEASE label
• Considered adding a ⚠️-CAUTION-WHEN-RELEASING label for higher risk changes

• Yes
• N/A

UI

Have you made changes in the ui layer and considered the following?

• Figma design screenshots
• iOS video/screenshots
• Android video/screens
• Snapshot testing
• Light/dark mode styles
• Accessibility settings

• Yes
• N/A

Data / Domain

Have you made changes in the data or domain layers and considered the following?

• Use case unit tests
• Model unit tests
• Logging unexpected errors
• Unsafe data validation

• Yes
• N/A