Oura: persist the ring's SleepNet hypnogram as a stage-timeline sleep session, shown honestly as "Oura"

[pipiche38]

Summary

The Oura ring banks its whole-night SleepNet phase codes (2-bit deep/light/rem/awake, 4/byte) in one burst after wake. This PR decodes that burst, reconstructs its time axis, refines the true sleep end with the 0x49 sleep-summary window, and upserts the night as a CachedSleepSession under the ring's own deviceId — so SleepMerge's imported-over-computed rule surfaces Oura's own staging instead of a computed guess. The sleep surfaces then label that night honestly as "Oura" with a caveat that its stages are the ring's raw on-device classification.

Two halves, both platforms, byte-identical Swift/Kotlin twins:

1. Persist the hypnogram (data)

• OuraProtocol (pure): HypnogramAssembler (30 s/code time-axis, laid backward from burst end), 0x49 sleep_summary decode + window pairing in OuraHistoryDrain, plus OuraEvents/Decoders/Framing/OuraDriver additions. No CoreBluetooth; covered by swift test / JVM tests.
• WhoopStore: OuraSleepSessionMapping (anchored per-code hypnogram → CachedSleepSession stage breakdown), OuraStreamMapping sleepPhase pass-through.
• App: OuraLiveSource assembles the burst, anchors it to ring-time, 0x49-refines the end, and calls persistSleepSession; SourceCoordinator wires the persist closure.

2. Show provenance honestly (UI)

A persisted Oura night is the ring's own SleepNet output — not a NOOP computation — so the surfaces say so, instead of the generic "On-device":

• One canonical resolver: DeviceBrandCatalog.isOura(deviceId) on both platforms (brand-table prefix, never an "oura" literal). Swift Repository.activeDeviceIsOura + Kotlin SleepScreen both call it.

• Labels: hero + main-sleep badges read "Oura"; daySourceBadge gains the Oura brand so the ring-id session (and By-Day) label correctly; WHOOP + Apple imports still win the provenance order above Oura.

• Honest caveat (ouraRawStagesNote): the stage caption reads "raw on-device stages", and a note states plainly:

  "This split is the ring's raw on-device classification read over Bluetooth, not the adjusted stages the Oura app shows. Expect more Awake and less Deep/REM here than in the Oura app for the same night."

  This is deliberate: the ring's raw BLE codes differ from the vendor's cloud-post-processed hypnogram, so the breakdown isn't mistaken for the Oura app's polished numbers.

• Design tokens only (restColor / textTertiary / caption); read/UI-only, not stored, never crosses .noopbak (no data twin needed).

Tier discipline

The persisted session is a ring-PROVIDED night, not a NOOP-computed score. Activity/MET (Tier-B) is untouched.

Tests — automated

• swift test OuraProtocol + WhoopStore green, incl. the new DeviceBrandCatalog.isOura case (both platforms).
• macOS Strand BUILD SUCCEEDED; Android compileFullDebugKotlin OK.
• ⚠️ The Android unit-test run is currently blocked by an unrelated 9.1.0 gap — Skin Temp, Wrong Strap Model #716 added DeviceRegistryDao.setModel without updating three test fakes, so testFullDebugUnitTest can't compile its source set. A separate one-commit fix (fix/android-registry-fake-setmodel) unblocks it; the Kotlin isOura test here mirrors the passing Swift one and runs once that lands. (PR Android: unblock testFullDebugUnitTest — implement DeviceRegistryDao.setModel in the three fake DAOs #725 is fixing it)

Tests — real hardware (2026-07-22, Oura Gen 3, macOS 9.1.0)

Validated end-to-end on a live overnight + nap, cross-checked against the WHOOP app for the same night.

Persist fired correctly:
0x49 sleep window candidate 22:09:31 → 08:25:31
hypnogram burst end refined by 0x49 — SleepNet write 12:15:37 → true sleep end 08:25:31 (−230 min)
hypnogram reconstructed [22:01:31 → 08:25:31, anchored] codes=1248
sleep session persisted [22:01:31 → 08:25:31] eff=70% → oura- (wins merge over computed)

Anti-phantom 0x49 refinement worked: the ring wrote the whole burst at 12:15 while on the charger; the refinement trimmed 3h50m of post-wake write-tail to a true end of 08:25 — without it, the night would have been mis-dated ending
at noon.

Oura vs WHOOP — close: onset 22:01 vs 22:13; wake 08:25 vs 08:02.

Stage split — diverges exactly as ouraRawStagesNote warns (raw on-device ⇒ more Awake, less Deep/REM):

Stage	Oura raw (this PR)	WHOOP
Awake	3:06 (30%)	1:16 (12%)
Light	5:16 (51%)	4:37 (49%)
Deep	1:13 (12%)	1:40 (16%)
REM	0:50 (8%)	2:16 (23%)
Asleep	7:19	8:33

The ~2.4× Awake and <½ REM is precisely the behaviour the caveat note describes — the honesty layer is doing its job, not a regression.

Also confirmed live:

• The nap persisted as a second Oura session: [13:59:31 → 14:25:31] eff=56%.
• UI: the Sleep screen shows the night labelled "Oura" (author-confirmed on device).
• Wear detection (Oura: live On-wrist / Off-wrist wear status #628): charger at 08:40 → worn again 10:01 — correct.
• Feature-status probe (Oura: read-only SpO2 / real-steps feature-status probe (confirm the server-flag gate) #710): SpO2 + real_steps both INACTIVE (server-gated) — reconfirmed.

Provenance ordering note: an Oura night shows "Oura" only while no WHOOP import covers that day; once a WHOOP export is imported for the same day, WHOOP wins the merge and the label flips to "Whoop" — by design.

Scope

Supersedes DRAFT #446 (oura-sleep-stage-timeline-persist). Clean single commit off main; no ibiHrDump/rawDump/activity-corpus carried in.

[pipiche38]

Still some work to do