fix(oura): gate RSA respiration to nil when the R‑R stream isn't beat-accurate

[pipiche38]

As described in #882 adding a beat-accuracy precondition to SleepStager.respRateFromRR (both platforms): a beat is "time-accurate" when its wall-clock gap matches its own R‑R value within beatAccuracyToleranceS (0.5 s); if fewer than beatAccuracyMinFraction (50 %) of beats qualify, return NaN (honest no-data) instead of a wrong ~10. General, not Oura-specific — WHOOP's beat-accurate R‑R (~100 %) and the synthetic RSA fixtures pass unchanged; Oura's banked IBI (~2 %) is gated. So the Oura night simply shows no respiration rather than a confidently-wrong one.

[vishk23]

Sequencing note between this PR and #877 — not an objection to either, and both are yours, so this is really just a "these two want an order" flag. They touch disjoint files (#877 is AnalyticsEngine + IntelligenceEngine, this one is SleepStager), so nothing in git will enforce it.

Short version: this one wants to land first.

The chain, verified on main @ e9326000:

AnalyticsEngine.swift:580-585
    let perSession = matched
        .map { SleepStager.respRateFromRR(rr, start: $0.start, end: $0.end) }
        .filter { $0.isFinite }

respRateFromRR has exactly one production call site per platform (AnalyticsEngine.swift:582, AnalyticsEngine.kt:413), and its input is matched — the day's sleep sessions.

Today a ring night contributes nothing to matched, because detectSleep bails before it starts:

SleepStager.swift:909-910
    let grav = gravity.sorted { $0.ts < $1.ts }
    if grav.count < 2 { return [] }

So respRateBpm currently comes out nil for a gravity-less owner — which #877's own new test asserts (testEmptyProvidedSleepIsByteIdenticalToOmitting). #877 is precisely the change that makes matched non-empty for that owner, so it is what first routes the ring's banked R-R into the RSA estimator. This PR's gate sits inside respRateFromRR, upstream of everything else in that function, so landing it first covers #877's new path on day one with no follow-up. The reverse order leaves a window where the ring's stream is estimated ungated.

Two things that make this less alarming than it first looks, both worth having on the record:

There is already a partial guard. respRateFromRR clamps its output to respPlausibleRangeBpm (8.0...25.0, defined SleepStager.swift:1484, applied :1589 — outside the band it returns NaN). This PR's description cites a collapse to "a confidently-wrong ~7–10"; the sub-8 part of that is already NaN'd on main today. The genuinely exposed window is roughly 8–10, not the whole range.

If a value does land in that window, the consequence isn't a false illness signal. I want to correct this before it becomes received wisdom, because I had it wrong myself until I read the code. Every live respiration consumer is one-sided upward:

• IllnessSignalEngine.swift:159-160 — let over = r.zIllnessward - signalZThreshold; guard over > 0 else { continue }. A negative z contributes nothing and isn't counted toward the corroboration gate.
• ReadinessEngine.swift:172,176 — if z >= 2.0 { .bad } else if z >= 1.5 { .watch }. No low branch.
• AppModel.swift:1465 — signal({ $0.respRateBpm }, cfgKey: "resp", illnessUp: true).

A spurious ~10 against a ~14–16 baseline is a negative z and fires no illness signal anywhere. What it actually does is:

1. Inflate Charge. The recovery respiration term is lower-is-better (RecoveryScorer.swift:341-343, commented "Resp term: lower is better"), so a fabricated low respiration reads as better recovery.
2. Contaminate the personal respiration baseline the illness z-scores are later measured against (IntelligenceEngine.swift:818 → :845-853 → :871; the "resp" baseline config accepts 4.0–40.0, so 8–10 folds in silently). Since that baseline is keyed by day rather than by device, a user running both a ring and a strap pulls the shared baseline down.

(2) is the one that eventually produces an illness false positive — but second-order and only after enough contaminated nights have shifted the baseline, not on the night itself.

None of this argues against either PR. It argues for #883 before #877, and I thought the reasoning was worth writing down since the two of them read independently.

Everything above is code-reading on main @ e9326000. I have no Oura ring, so I have not independently reproduced your ~2% beat-accuracy figure or the observed ~7–10 — those remain your device observations. Thanks for splitting these into two focused PRs; it made the interaction much easier to see. @pipiche38

[pipiche38]

As pointed by @vishk23 , @ryanbr if you are happy to merge the PR, please do merge #883 first and then #877

[pipiche38]

@vishk23 Agreed on all three points, and confirmed against the code:

• The existing guard is real — respPlausibleRangeBpm = 8.0...25.0 (SleepStager.swift:1488). The catch is that the confidently-wrong Oura value (~10 bpm) sits inside that band, so the clamp can't reject it. The beat-accuracy precondition here catches it upstream by returning NaN (→ no-data, not stored).
• The sequencing is right, and Score an Oura night by feeding the ring's own hypnogram into the scorer (#804 Fix A) #877 line 651 is the precise trigger: AnalyticsEngine.swift:651 computes respRateFromRR over the main-night window. Today an Oura-only night has no sleep session (0 gravity), so matched is empty and that line never runs — respiration stays nil. Score an Oura night by feeding the ring's own hypnogram into the scorer (#804 Fix A) #877 makes the night score from the ring's hypnogram, first reaching line 651 — so Score an Oura night by feeding the ring's own hypnogram into the scorer (#804 Fix A) #877 opens the ungated window, and this PR is the gate that closes it.
• Second-order effect confirmed: ~10 bpm is below baseline → negative z-score, so no false illness signal — but it's still a wrong stored value inflating Rest/recovery and contaminating the respiration baseline.

So: land #883 before #877. No code change needed here — the NaN path is the complete fix; the only concern is merge order.

[pipiche38]

I'm sorry , but this is not going as my expected speed, and this is an handicap for my development. I don't want to spend too much time in just rebasing all my PRs.
I understand that @ryanbr is the only maintenair. Appreciate the work you are doing.

So I'm closing all those PR .

Feel free to take over what I was doing ...