fix(sleep): motion-corroborated wake — elevated HR alone no longer scores WAKE on a motionless wrist (fixes #462)

[vishk23]

Summary

Both stagers (SleepStager V1 and the default SleepStagerV2) and the HR-led session confirmation (confirmSleepWithHR) called WAKE primarily off HR / HR-variability with no motion or posture cross-check. On a night whose resting HR is held elevated without the wearer getting up — a supplement protocol, a fever, a hot room, alcohol — that logic scores hot-but-motionless sleep as wake: it over-calls WASO, mis-places onset, and tanks efficiency and Rest.

The rule: elevated HR alone is insufficient to call wake. An epoch or run at the night's quiescent motion floor with unchanged posture cannot be scored WAKE on cardiac evidence alone. Corroboration comes from the gravity posture/jerk signal both stagers already consume (always present) — not step ticks.

The two evidence nights

Two confirmed real nights motivated the fix; details are in #462 rather than duplicated here (2026-07-13: 194 min WAKE vs ~67; 2026-07-14: onset 1:41 vs ~1:29 plus a 44-min WAKE block).

Why #402 didn't cover it

Upstream #402 is a default-OFF post-pass over an already-staged hypnogram, gated on step density. This change instead acts where the mis-scoring is produced — the stager emission and the HR-led session confirmation — is on by default, and reads the gravity posture/jerk signal rather than step ticks, so it applies to WHOOP nights that carry no step stream.

What changed, per layer

• SleepStagerV2 (default) — motionQuiescent + awake cardiac clamp. On a motion-quiescent epoch (no observed movement; peak jerk at/below the night-relative wake-gate floor) the AWAKE cardiac term is clamped to ≤ 0 — the wake-suppressing (low, flat HR) half is kept, the wake-promoting half dropped. The clamp is applied over upstream's restored (post-fix(sleep): restore pre-#348 V2 staging defaults — DREAMT wake tune over-calls awake in the field (#431) #437) 0.8·zhvv + 0.4·zhrv coefficients, so any epoch that actually moved stages byte-identically; only a still, elevated-HR epoch is held.
• confirmSleepWithHR (V1 detection) — motion corroboration. When a run is deeply motion-quiescent (≥ ~90% of its dense-gravity minutes posture-stable, over ≥ 20 such minutes via runIsDeeplyQuiescent / posturVarianceG2), the HR sleep band widens ×1.05 → ×1.30. The band keeps a floor (genuine all-night in-bed wakefulness is still dropped); with no gravity evidence the strict band stands. Both helpers are pure and deterministic.
• adaptiveOvernightHRBaseline + sleepHRBaseline threading. An optional personalised overnight band (median of recent overnight medians, floored) threaded through detectSleep as an argument defaulting to nil (byte-identical when unset). Live cross-night wiring in IntelligenceEngine is a deliberate follow-up.

Verification

swift test in Packages/StrandAnalytics is green — 1077 tests, 0 failures, including 8 new MotionCorroboratedWakeTests and every SleepStager / SleepStagerV2 / WakeMotionRefinement golden suite (the byte-identical default path — empty gravity, nil baseline — is preserved).

Cross-platform / Kotlin twin

Kotlin twin included + gradle-tested. The com.noop.analytics stagers carry the same policy transcribed byte-identically: SleepStager.confirmSleepWithHR gains grav + sleepHRBaseline corroboration with runIsDeeplyQuiescent / posturVarianceG2 / adaptiveOvernightHRBaseline (and the x1.30 / floor / 90% / 20-min / 40 bpm constants), sleepHRBaseline threaded through detectSleep and folded into the memo key; SleepStagerV2.motionQuiescent clamps the awake cardiac term ≤ 0 on quiescent epochs over the same coefficients. MotionCorroboratedWakeTest mirrors the 8 Swift fixtures. ./gradlew :app:testFullDebugUnitTest --tests "com.noop.analytics.SleepStager*" --tests "com.noop.analytics.MotionCorroboratedWakeTest" → 85 tests, 0 failures, with the detect-memo fingerprint parity golden and the V2 staging golden intact (the byte-identical default path — empty gravity, nil baseline — is preserved by construction).