[UtkuDenizAltiok]

What this PR does

SleepStagerV2.respRegularity (the RSA respiration-regularity term) runs once per 30-second epoch and evaluated cos/sin for every in-band bin and every resampled point, each time: ~53 bins × ~836 points, so ~45k pairs per epoch and ~45 million per night. The factors depend only on the 4 Hz grid length n, and a night's beat window is whole seconds wide, so a night sees only a handful of lengths. This computes each length's factors once per night in a small table (RespDFT / RespDft), with the very expressions the transform used inline, so the result is bit-identical. Both platforms.

Measured on a real WHOOP 5.0 store (a backup, 4.5 days; iPhone 17 Pro simulator, Release):

• Time Profiler: in the first re-score of a process (every night staged cold), respRegularity + __sincos_stret were 0.64 s of 5.0 s CPU (13%).
• First (cold) pass, alternating builds (upstream/main vs this), two rounds: 4.9 / 5.0 s → 4.5 / 4.4 s CPU. Warm passes are unchanged there, because that harness's synthetic offload lands after the night and the stager's own cache serves it; a pass that re-stages a growing night (every overnight re-score) saves the same per-epoch work.
• Memory: one table per distinct n per night, ~53 × ~836 × 2 doubles ≈ 0.7 MB each, dropped with the night.

Type of change

• Refactor / cleanup (same results, less work)

How it was tested

• Swift: SleepStagerRespDFTTableTests keeps the function as it was, verbatim, and compares bit patterns with the table version over 3,000 random beat windows built the way features() builds them (whole-second times, 0–2 beats a second, full-width and short/sparse windows, >2,000 reaching the transform, >3 grid lengths sharing one table), plus a check that a warm and a fresh table give the same answer. Release and debug both pass. With the table's sine one ulp off (.nextUp), 2,125 comparisons fail; restored byte-identical (sha256).
• Kotlin: SleepStagerRespDftTableTest, the same design against SleepStagerV2.respRegularity. Android CI on the fork: green (6,536 tests); with the table one ulp off (a throwaway branch), exactly this test fails.
• Tools/SleepPSG: swift test (port validation, 33 tests) passes: the shipped stager and the recipe port still agree on every epoch label.
• Parity: respRegularity is now a declared twin pair (both docs name the other), and the refreshed derived inventory is in the commit: function pairs 206 → 207, unpaired functions −2. parity_ledger.py: no new findings; parity_ratchet.py: 0 errors.
• Full local run on 7c298e93 (on 0c982899), every step passed: WhoopStore 629 · StrandAnalytics 2083 · StrandImport 327 · doc lint · i18n · parity ledger · ratchet · governance (124) · macOS StrandTests 2,244 (only the two locale-dependent TodayCarryOverTests) · iOS build.

Checklist

• Swift package tests pass for any package I touched (swift test in Packages/StrandAnalytics)
• Android unit tests pass if I touched android/ (fork CI)
• No new build warnings introduced
• Follows the conventions in docs/CONTRIBUTING.md
• I did not commit generated output (Strand.xcodeproj/) or any secrets/keystores

Related issues

Refs #1538

🤖 Generated with Claude Code

[ryanbr]

@UtkuDenizAltiok Reviewed. 18/18 green. The bit-identity argument is the whole change and it holds.

The table builds each factor with the same expressions the transform used inline, same w, same a = w * j, same accumulation order, so reading it back is bit-for-bit what recomputing gave. The cache key is n alone and that is sufficient because kLo and kHi are pure functions of n, so no two calls with the same n can want a differently shaped table. On the Kotlin side -2.0 * PI * k / n groups identically to the inline expression it replaces, so each platform preserves its OWN prior output exactly, which is the right contract here: this change is not making the two platforms agree, it is leaving each where it was.

The tests are the strongest part, and they do the two things a memo change needs.

XCTAssertEqual(now?.bitPattern, before?.bitPattern) against a verbatim copy of the old function is the correct assertion. A tolerance would have passed a change that moved stage labels. And two guards stop the equality from being vacuous: nonNil > 2000 of 3,000 windows, so most comparisons reach the transform at all, and dft.count > 3, so several grid lengths genuinely share one table rather than the cache being exercised once. I have shipped a vacuous equality test in this repository myself, so I went looking for exactly that and did not find it.

testTheAnswerDoesNotDependOnWhatTheTableHeldBefore is the hazard specific to memoisation: a warm table must not make a later window answer differently from a cold one. Having both tests means a correct implementation and a correct cache are checked separately.

One thing I checked that is not visible from your branch. #2576 landed after you opened this and widened Kotlin baseLogPrior from private to internal, in the same files. A visibility change can move what the ledger sees, and #2576 touched no Tools/parity_* path so parity-governance never ran on it. If that had left main's stored authority unreproducible, your re-derived authority would have been computed against the wrong tree. It did not: the ratchet on main reports errors=0, and main's authority is byte-identical to the base you derived against, so both trees carry the same declaration set and your twin_map delta stays correct across the rebase.

One note, not a defect. Each table is about 53 x 836 x 8 bytes twice over, so roughly 700 KB per distinct n. The window is fixed width, so a night sees one full-width n plus a few edge cases and holds a few megabytes that go when the night does. Worth a reader knowing; not worth changing.

The 13 % figure is consistent with what a field log shows independently: on a 5.0/MG install this morning, cold re-score passes spent 68 to 80 seconds in read and prep against 3 seconds scoring, so shaving the per-epoch transform is aimed at the right half of the pass.

Taking it.