feat(sleep): motion-aware wake refinement behind an Experimental toggle (#364 follow-up)

[vishk23]

What

Follow-up to #364 "Proposal 2 (motion-aware wake classification) — great, but a follow-up", and a companion to the sparse-motion discipline from #345.

Adds WakeMotionRefinement (Swift Packages/StrandAnalytics + a Kotlin twin in com.noop.analytics): a post-pass over the already-staged hypnogram (V1 or V2, unmodified) that reclassifies a scored wake segment to light when its per-minute step-tick cadence shows no locomotion and its per-minute gravity posture is stable outside a minority of isolated turn-over burst minutes (which are kept as wake, ±1 min). It never touches the stagers' own HR-led emission models — both call "wake" primarily off HR/HR-variability, and this pass is exactly the locomotion/posture cross-check that path skips.

The real-world failure this fixes

A WHOOP 5.0 night with pharmacologically-elevated heart rate (a supplement protocol, not illness) scored 194 min wake across ~6.4h in bed (efficiency 0.50), though the wearer reported sleeping through. Minute-level review of the four largest wake blocks found zero walking cadence: each was a single-minute turn-over burst (20-36 step-motion-counter ticks, a posture-variance spike) bracketed by minutes of complete stillness (posture variance < 0.01, zero ticks) — recurring on a ~90-min rhythm consistent with hot-but-atonic REM being scored as wake, not a real awakening. The phone recorded zero steps all night. A genuine get-up looks entirely different: sustained multi-minute walking cadence, not an isolated single-minute blip. No personal data is included here or in the diff — every test fixture is synthetic.

Density self-gate (#345), not a family string

ryanbr flagged in #364 that WHOOP 4.0's gravity stream is often too sparse to tell "restless in bed" from "out of bed," so motion-aware classification would need to self-limit to dense-motion straps. This lands that as a genuine data gate, not a model check: isMotionDense requires that at least 80% of the scored window's minutes carry enough gravity samples to compute a real per-minute variance (a single sample has zero variance by construction and would silently rubber-stamp "stable") and enough step records to know a zero-tick minute is a real zero rather than a missing stream. A WHOOP 4.0 fails this on the data itself every time — it never emits a step sample at all, and its gravity is banked at roughly one vector per minute — so it's untouched regardless of the toggle. A WHOOP 5.0/MG streams both channels densely and is this refinement's expected beneficiary. Threshold numbers are open to tuning; they're fixed a-priori from the one reference night above, not fit to labels, exactly like the honesty bar the sparse-gravity work set.

Honesty / default-off

Ships behind PuffinExperiment.motionAwareWake (Strand/BLE/PuffinExperiment.swift + the Kotlin twin), default OFF — a derived physiological signal with one reference night behind it, per the repo's rule for exactly this situation. The pass only ever shrinks an already-scored wake segment; it never invents wake time, and detection plus the V1/V2 staging engines are byte-identical either way. Toggle row added next to "Sleep staging (V2)" in Settings → Experimental on both macOS/iOS and Android.

Tests (synthetic fixtures only — no real user data)

• testHotButStillNightReclaimsTheStillSpansAroundIsolatedBursts — a still night with a turn-over burst every 90 min: the still spans reclaim to light, the two burst blocks (±1 min) stay wake, total duration is exactly conserved.
• testRealGetUpStaysWake — 3 consecutive minutes at 25 ticks/min (a real get-up) trips the sustained-walk locomotion gate; the segment is left untouched.
• testSparseMotionNightDeclinesToAct — the same burst pattern as the first test, but WHOOP-4.0-shaped density (sparse gravity, no step samples): the gate declines and output is unchanged, isolating density as the only variable.
• testToggleOffIsByteIdenticalPassthrough — enabled=false is byte-identical on a fixture proven live when enabled (so the assertion isn't vacuous).
• testRecoversDifferentInjectedReclaimAmountsAcrossPatterns — the repo's hard rule for a derived signal ("prove the method tracks a varying input, not one lucky match"): five distinct synthetic patterns (single burst, well-separated bursts, adjacent bursts whose padding overlaps, edge-clamped bursts) each inject a different reclaim amount, and each is recovered exactly.
• testSessionLevelRefineRecomputesEfficiency — the SleepSession/DetectedSleep convenience wrapper recomputes efficiency from the refined stages and carries restingHR/avgHRV over unchanged.

Mirrored 1:1 in WakeMotionRefinementTest.kt.

Verification:

• swift test in Packages/StrandAnalytics: 1026/1026 passing (full suite + 6 new).
• xcodegen generate && xcodebuild -scheme Strand -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO build (the Settings toggle row touches app-target UI): BUILD SUCCEEDED.
• ./gradlew compileFullDebugKotlin: clean.
• ./gradlew testFullDebugUnitTest: 2632/2632 passing (full app suite + 6 new), 1035/1035 in com.noop.analytics alone.
• ./gradlew assembleFullDebug: BUILD SUCCESSFUL.

Android

The Kotlin analytics layer structurally mirrors Swift closely enough to transcribe directly, not just conceptually: StageSegment/DetectedSleep are field-for-field twins of StageSegment/SleepSession, SleepStageHealer.restageFromSamples is the exact analog of Repository.restageFromRaw, and PuffinExperiment.kt already mirrors the Swift toggle registry key-for-key. So this PR transcribes the full post-pass (WakeMotionRefinement.kt, same constants, same algorithm) rather than skipping it, and wires it through the same call sites the existing experimentalSleepV2 flag uses end to end: SleepStageHealer, both IntelligenceEngine.analyzeRecent/analyzeRecentOnCpu signatures, the three Context-aware callers (AppViewModel.kt x2, WhoopBleClient.kt), and a SettingsScreen.kt toggle row next to the existing V2 switch.

Threshold tuning

The constants (sustainedWalkTicksPerMinute=10, singleMinuteWalkTicks=40, stablePostureVarianceG2=0.05, minStableMinuteFraction=0.80, burstPadMinutes=1, the density-gate floors) are named, documented, and fixed a-priori from the one reference night in the issue thread — happy to tune any of them against more real 5.0/MG data if you have nights to compare against, or to adjust the density-gate floors if they're stricter/looser than the sparse-gravity work already implies.