Readiness: fold HRV/RHR through the spine in a window-fold mode (stacked on #456)

[vishk23]

Stacked on #456 (Wave 0). RD2 folds through the log-domain HRV z that #456's RD1 introduced, so this branch carries #456's commits underneath and the diff shows them until #456 lands, at which point I'll rebase to just the readiness commit. Review target = the single readiness commit on top.

Readiness: fold the HRV/RHR baselines through the shared spine — in a window-fold mode that adapts

ReadinessEngine z-scored today's HRV/RHR against a naive mean + sample SD over the trailing 30 nights. Two defects: a single freak night inflates that SD (so a real drop under-flags for weeks until the outlier rolls out), and a tight baseline saturates the z. The app already has a robust baseline engine (Baselines: Winsorized-EWMA, σ-floor, recency-weighting) — but adopting it naively is wrong for readiness, and finding out why is most of this PR.

Why not just call Baselines.foldHistory

The spine's hard-outlier rejection (>5σ → discard) is correct for the RecoveryScorer's incremental nightly fold. But readiness re-folds a trailing window every call, and a recent sustained shift (a fitness change, or an Oura→WHOOP device swap, or a supplement onset) lands at the window's end — past the young-adapt grace period — so rejection discards the new normal as a run of "outliers" and readiness keeps scoring you against a stale baseline. Replayed on real HRV history, a settled 140 ms → 85 ms window keeps the baseline at 140 and flags every new-normal night as a catastrophic drop.

The fix: a window-fold mode

Baselines.update / foldHistory gain rejectHardOutliers: Bool = true (default preserves the RecoveryScorer exactly). Readiness folds with it off: Winsorization still damps a single freak night (clamped to ±3σ, not folded raw), but a sustained shift is followed instead of rejected — each night nudges the center and widens the spread until the new level is no longer an outlier. Single spike damped; sustained shift adapted — the distinction the naive path and the incremental spine both get wrong in opposite directions.

HRV folds in the log domain (RD1 already z-scores lnRMSSD; the new readiness_hrv_ln config carries the ln-space bounds/floor), so Winsor-clamping composes with the log transform instead of fighting it. RHR uses the raw resting_hr config. Resp keeps its special plausibility-gated path for now.

Validation (real 420-night HRV history)

The design was chosen by replaying all the candidates — naive, naive+σ-floor, full spine (reject on), Winsor-EWMA (reject off), median/MAD — over two years of real nightly HRV:

• Outlier damping: the history has 7 genuine single-night outliers (28–46 ms freak nights, some matching the known Oura import-bug signature). In a window containing one, naive's SD is 0.291 vs the Winsor-clamp's 0.220 — naive is 32 % wider, so it under-flags a real drop for ~2–4 weeks. Reject-off + Winsor keeps it tight and adapts.
• Adaptation: on a sustained step the window-fold's center follows within ~2–3 weeks; the reject-on spine stalls. Both correctly still flag a genuine one-night drop.

New RD2SpineTests pin the reject-on-vs-off capability, single-freak damping, sustained-shift adaptation, and that a genuine low still flags; the RD1 geometric-baseline test is updated for the Winsor-EWMA center. Full StrandAnalytics suite green; macOS build green.

Notes

• Swift-first; Kotlin twin (Baselines.update/foldHistory reject flag + the ReadinessEngine fold) not included here.
• Additive: every existing foldHistory/update caller is byte-identical (rejectHardOutliers defaults true). Only readiness opts into the window-fold mode.

[ryanbr]

Reviewed. This is strong work — the reasoning for not reusing foldHistory naively is the valuable part, and it is the kind of thing that usually gets discovered in production instead of in a PR description.

Verified

• The arithmetic. minVal: 2.079 / maxVal: 5.521 are ln(8) and ln(250) to four places. Correct.
• Genuinely additive. rejectHardOutliers: Bool = true on both update and foldHistory, and the gate becomes rejectHardOutliers && state.nValid >= minNightsSeed && !isYoung. Every existing caller is byte-identical, as claimed.
• CI is green for real. test (StrandAnalytics) passes, along with the other packages. swift-packages.yml is the one active workflow in this repo, so package-level changes like this get genuine coverage — worth saying, because app-target changes get none.

The concern I came in with, and why it is smaller than I thought

Turning off hard-outlier rejection means the fold cannot distinguish "a new normal" from "sustained bad data", and this codebase has form: #631 zeroed every imported journal answer, #677 stamped Oura IBIs at the wrong time. A month of plausible-looking wrong HRV would silently re-baseline readiness.

I checked the ordering before raising it, and it is largely handled: the plausibility guard (cfg.minVal <= value <= cfg.maxVal → skip-and-hold) runs before the reject gate, so with rejection off, anything outside 8–250 ms in ln space is still skipped, not folded. The residual exposure is sustained wrong-but-plausible data — which is genuinely indistinguishable from a real physiological shift, so following it is the defensible choice.

Worth one sentence in the rejectHardOutliers comment saying the range guard still applies. The comment currently explains what rejection stops doing without noting what still bounds the fold, and the next reader will arrive at the same worry I did.

Not mergeable yet — and the order matters

1. The stack is real. All fifteen of #456's files are inside this PR's seventeen; the two that are yours alone are Baselines.swift and RD2SpineTests.swift. So merging this as-is lands #456 wholesale. Your note already says you will rebase once #456 is in — flagging it here so nobody merges past it. Order: #456 → rebase → this.

2. The Kotlin twin is the blocker. You call it out honestly, and CLAUDE.md's contract does allow "explicitly call out why not" — but the consequence here is not cosmetic. The Android ReadinessEngine.kt change in this diff belongs to #456's RD1; the RD2 window-fold is Swift-only. So after this lands, iOS readiness would fold through the Winsorized-EWMA spine while Android keeps the naive 30-night mean + SD — the same wearer, the same night, two different readiness scores. That escape clause is meant for divergence that is harmless or unavoidable, and a headline score differing per platform is neither.

The Swift work is the hard part and it is done; Baselines.update/foldHistory gaining a defaulted flag and ReadinessEngine opting in should port fairly mechanically, with RD2SpineTests mirrored as RD2SpineTest.kt alongside the four Kotlin twins already here.

One caveat, not a defect

The candidate selection — naive vs σ-floor vs reject-on vs reject-off+Winsor vs median/MAD — was replayed on a single 420-night history, and floorSpread: 0.08 is calibrated to "a real wearer's own ln-HRV spread (~0.10)". That is far more evidence than most changes here arrive with, and I am not asking for more before merge. But it is one wearer, and the floor is a global constant, so if a second history is ever available it would be worth re-running the same replay against it — particularly the σ-floor, since that is the parameter most likely to be person-specific.

[ryanbr]

Stack-level note

Reviewing #456 and #469 back to back turned up one systemic thing that neither review says on its own, since there is no tracking issue carrying the pair.

Both PRs leave Android's scoring behind, one layer apart.

• Wave 0 scoring: wire computed-but-disconnected methodology into Rest + readiness #456 ports the Kotlin capabilities (RestScorer.personalizedNeedHours, log-domain z, ScoreConfidence.readiness) but not the SL1/T1 wiring — IntelligenceEngine.kt's analyzeDay call never passes sleepNeedHours or sleepConsistency, so Android Rest keeps the neutral consistency and the 8 h default.
• Readiness: fold HRV/RHR through the spine in a window-fold mode (stacked on #456) #469 is Swift-only for the RD2 window-fold, so Android readiness keeps the naive 30-night mean + SD.

Landing both as they stand means iOS and Android disagree on Rest and Readiness — two headline scores — for the same wearer on the same night. RD1 and RD-confidence are fine; those live inside engines that were ported.

Suggested order:

1. Wave 0 scoring: wire computed-but-disconnected methodology into Rest + readiness #456 + the Kotlin IntelligenceEngine wiring, rebased onto current main, CI re-run — its green run is 236 commits old.
2. Rebase Readiness: fold HRV/RHR through the spine in a window-fold mode (stacked on #456) #469 onto the landed Wave 0 scoring: wire computed-but-disconnected methodology into Rest + readiness #456, so its diff narrows to the readiness commit as intended.
3. Readiness: fold HRV/RHR through the spine in a window-fold mode (stacked on #456) #469 + its Kotlin twin (Baselines.update/foldHistory reject flag, the ReadinessEngine fold, RD2SpineTest.kt).

The Swift work in both is the hard part and it is done — the analysis, the candidate replay, and the reasoning for not reusing foldHistory naively are all genuinely good. What is missing is mechanical by comparison, and it is the part the parity contract cares about.

One more thing worth flagging for whoever lands these: both change scores for existing users. #456's SL1 replaces a flat +5-for-everyone consistency term and T1 replaces a fixed 8 h need; #469 changes the readiness HRV baseline. All corrections rather than tuning, but Rest and Readiness will visibly move, and re-scored history moves with them. Worth a release-note line so it reads as an intended fix.