fix(oura): gate RSA respiration to no-data when the R-R stream is banked

[pipiche38]

Re-land of #883, which was closed in the 2026-07-31 batch rather than on merit. Reworked onto
HRVAnalyzer.beatAccurateFraction (#1108 landed the canonical definition after #883 was written), and
re-validated on two fresh nights — which corrected the original writeup in three places.

The problem

An Oura night reports a respiratory rate that looks entirely normal, while a WHOOP strap worn on the
same nights measures ~16.4. Respiration is derived by RSA from the R-R stream, and the ring's banked
overnight IBI cannot support RSA: it stores R-R values against coarse per-record timestamps, so the
beat-to-beat variation RSA reads is not in the data.

The fix

respRateFromRR (both platforms) refuses a stream that is not beat-accurate, calling
HRVAnalyzer.beatAccurateFraction / beatValuesAreTrustworthy instead of carrying a second copy of the
same judgement and its two constants. That is the collapse #1108's body promised — one boundary, one
definition, so a threshold change moves respiration and SDNN together instead of letting them drift.
WHOOP R-R and the synthetic RSA fixtures measure ~100% and pass unchanged.

Measured, 2026-08-07, two real nights

31,460 and 30,754 in-bed beats, through the real SleepStager.respRateFromRR (temporary probe
against Packages/StrandAnalytics), plus a port validated against it — both synthetic fixtures
reproduce (15.0000 / 10.9091) and both nights reproduce NaN — used to switch the gate off, since the
Swift constants are static let.

	Night 1 (08-05→08-06)	Night 2 (08-06→08-07)
beatAccurateFraction	0.0246	0.0235
shipped path	NaN	NaN
gate OFF, splice-skip ON	NaN	NaN
both disabled	13.33 bpm	13.33 bpm

Three corrections to the original #883 writeup — all of which strengthen it

1. The number is 13.33, not "~7–10". It sits inside respPlausibleRangeBpm (8–25) and inside the
real adult sleeping range, so the range clamp is no protection whatsoever. Only 1 of 113 and 0 of
114 windows fall below 10 bpm. This also answers @vishk23's reading in
#883 (comment) — the exposed band is
not 8–10 with the sub-8 part already clamped; it is dead centre. Everything else in that comment holds,
and the consequence chain it traced (Charge inflation via the lower-is-better recovery term →
contaminated "resp" baseline → second-order illness FP, no same-night false positive) is the right
one. It is just worse than it looked: a fabricated 13.3 is indistinguishable by eye from a real reading.

2. The estimate carries zero information. Shuffling or reversing the night's R-R values returns the
same 13.3333 to four decimals, on both nights. The tachogram's breath band is a flat 1/f shelf with
no peak (neighbouring bins at 0.86–0.96 of the maximum); 13.33 is the peak-picker's own floor on the
4 Hz grid, given its 2.5 s minimum distance. That is the #194 bar failed outright — hence a gate on
banked-ness, not on whether the output looks sane.

3. The mechanism in the old comment was wrong. The time axis is not corrupted: sum(R-R) over wall
span is 1.030 / 1.008, so beat-time reconstructs the night to 1–3%. What is unusable is the interval
values — the ~6.6 s record decomposed into ~6 intervals whose sum is right to ~1% while the
individuals are not beat-to-beat measurements, the same decomposition already documented on
beatValuesAreTrustworthy. Proof: the batched fixture, run ungated, returns the correct 15.0, because
cumsum recovers relative beat timing. Banked timestamps alone do not break RSA.

Why both this and #977's splice skip are kept

They catch opposite banking geometries, and neither subsumes the other — now pinned by a test:

• [hrv] classifyCoverage has a ceiling and no floor, so an under-covered night reads as plausible #977 catches banking that TILES time — the real ring. A ~7 s record boundary against a ~1.1 s
  interval reads as a splice; on these two nights it independently discards 113/113 and 114/114
  windows. (So on this firmware the gate is the second lock. See the sequencing note below.)
• This catches banking that COMPRESSES time — the batched fixture stamps 6 beats per single second,
  so no gap ever exceeds rsaGapToleranceS and [hrv] classifyCoverage has a ceiling and no floor, so an under-covered night reads as plausible #977 is blind to it.

A firmware that changes its record period moves a stream from one geometry to the other without warning.

Known limitation, pinned deliberately

The gate detects banking by its symptom — coarse, repeated timestamps — and that symptom is a
transport artifact that is trivially repairable. Re-timing each record's beats by cumsum from the
record's own timestamp moves the fraction 0.0246 / 0.0235 → 0.875 / 0.863, defeating both this gate
and #977 — while the estimate stays 13.3333 and stays unchanged under shuffling. A well-meant decoder
change that distributes beat timestamps within a record would silently switch respiration back on for a
stream carrying no breathing information.

testRetimingABankedStreamDefeatsTheGate_knownLimitation fails the day that happens, and says what to
do: re-base the gate on provenance (was this stream banked?) rather than on timestamp shape.

Sequencing vs #877

#877 is what first routes a ring night into the estimator (detectSleep currently bails on a
gravity-less owner, so matched is empty and respRateBpm comes out nil). Landing this first covers
that path on day one — worth doing, and free.

Honest caveat on the urgency: on this firmware the exposure window is empty. #977's splice skip
already returns NaN on both nights, so merging #877 first would still yield nil. The ordering is
belt-and-braces, not a live bug — but the geometry argument above is exactly why I would not rely on
that staying true.

Verification

• Swift StrandAnalytics 1270 / 0 (RespRateRsaTests 7/7, 3 new).
• Android compileFullDebugKotlin clean; testFullDebugUnitTest 3554 tests / 3 failed — all 3
  (AiCoachContextTest, 2× StandardHrSensorFormatTest locale) reproduce on clean upstream/main,
  pre-existing.
• Both platforms carry the same gate, the same constants (now via one shared definition), and the same
  four fixtures.
• Analytics-only; no BLE path touched, so no hardware behaviour changes.

Still untested

Neither capture contains a beat-accurate R-R stream (rrInterval is 100% Oura; the WHOOP rows are
import-only with no R-R), so the gate's false-positive direction — refusing a stream it should
accept — is still covered only by the synthetic fixtures. A WHOOP night streamed rather than imported
would close that.

[ryanbr]

Cross-ref: this gate has an unintended interaction with WHOOP 4.0 — see #1331.

WHOOP 4.0's R-R is over-counted (#1008 stamps several R-R in one coarse second), which is timing-indistinguishable from an Oura banked stream, so the beat-accuracy gate here catches 4.0 too and blanks respiratory rate on every 4.0 night (regression since V10). The gate itself is correct — 4.0's over-counted beats genuinely can't support RSA (beat-time is rebuilt from the R-R values, so duplication reads the rate low). The real fix is the #1118 two-channel R-R de-dup, after which 4.0 passes this gate legitimately. Noting here so the interaction is on record.