[vishk23]

Fixes the design bug in SleepStagerV2.cyclePrior documented in #930, in the direction that issue and its follow-up comment argued for: graded rather than a cliff, absolute minutes rather than a fraction of session length, measured from a detected onset rather than from the window start.

Read the "what this is not" section before the numbers. This is a robustness fix. It does not buy accuracy, and I am not claiming it does.

---

The change

Packages/StrandAnalytics/Sources/StrandAnalytics/SleepStagerV2.swift, Kotlin twin at android/app/src/main/java/com/noop/analytics/SleepStagerV2.kt:

-static func cyclePrior(_ c: Double) -> [String: Double] {
+static func cyclePrior(_ c: Double, _ minutesSinceOnset: Double) -> [String: Double] {
     ["deep": 1.2 * max(0.0, 1.0 - c / 0.55),
-     "rem": 1.0 * c - (c < 0.12 ? 3.0 : 0.0),
+     "rem": 1.0 * c - remLatencyGuard(minutesSinceOnset),
      "light": 0.0, "awake": 0.0]
 }
+
+static func remLatencyGuard(_ minutesSinceOnset: Double) -> Double {
+    remLatencyPenalty * min(1.0, max(0.0, 1.0 - minutesSinceOnset / remLatencyMinutes))
+}
+static let remLatencyPenalty = 3.0    // K
+static let remLatencyMinutes = 60.0   // M0

So: K · clamp01(1 − m / M0) with K = 3.0, M0 = 60 min, where m is minutes since a measured sleep onset.

The 1.0 * c ramp and the whole deep term are untouched, deliberately. Both are correctly fractions of the session — they describe where in the night you are, which is inherently proportional. Only the latency guard changes units, because only it describes an absolute physiological interval. Ablating the ramp entirely collapses REM to 1.4 % of night and kappa to 0.143 (sleep-accel, LOSO), so it is load-bearing and I did not touch it.

---

What this is NOT

There is no accuracy win here, and reviewers should not accept one. On sleep-accel the -3.0 step is measurably inert:

	with the step	step removed
kappa (4-class, LOSO)	0.349	0.349
median first-REM latency	142.0 min	141.0 min

All 210 tested grid cells — {cliff, graded} x {fraction, minutes} x K in 1..8 x threshold — tie, because the recipe's own first-REM latency already sits beyond every guard width tested. The step is not currently doing anything to accuracy on that cohort.

The justification is that the term is parameterised in the wrong units, which is a correctness property, not a score. A term that is inert today on one cohort is not thereby correct; it is untested. Anchoring it in minutes means it stays inert for the right reason instead of by arithmetic coincidence.

---

Why minutes, and why that part is settled (CONFIRMED)

Measured on PhysioNet sleep-accel (Walch et al., SLEEP 2019; ODC-By v1.0), n = 31 subjects / 26,773 PSG-scored 30 s epochs, leave-one-subject-out:

• True first-REM latency is uncorrelated with session duration: Pearson r = -0.058, Spearman -0.076 (n = 30 subjects with a scorable first REM period).
• Re-expressing latency as a fraction of session makes it more variable, not less: CV 0.617 as a fraction vs 0.537 in minutes.
• Continuous elapsed time beats a threshold at equal feature count: binary c < 0.12 adds +0.009 kappa over physiology alone; continuous time adds +0.051. A threshold captures ~18 % of what continuous time provides.

The shipped guard works on that cohort only by coincidence — 12 % of a near-uniform 476-min recording is 57 min, just under the 88.5-min median true latency. That cohort spans only 2.4x in session length, so it understates the problem. On my own device database (n = 36 recorded sessions, one WHOOP 5 wearer) sessions span 11.5x and the guard width therefore ranges 7.4 - 84.5 min for the same wearer and the same physiology, exactly as reported in #930.

Provenance of the sleep-accel figures: the harness compiles SleepStagerV2.swift verbatim and reproduces 11,460 / 11,460 epoch labels identically across 48 randomised nights against the in-app stager, so these measure this code, not a re-implementation of it.

Choosing K and M0

K = 3.0 — the incumbent step's own magnitude, kept on purpose. e^-3 ~ 0.05 on the REM emission: strong suppression that sufficient evidence still overcomes, never a veto (#930 established the step was never a hard mask — REM still occurred at 6.8 % during hour 0 as shipped). Since all 210 grid cells tie, nothing in the data discriminates K. The smallest correct change fixes the units and the shape without also retuning a magnitude no measurement can justify. Note the graded form is strictly gentler in aggregate: mean penalty over [0, M0] is K/2 = 1.5 against the incumbent's flat 3.0.

M0 = 60 min. Cost against PSG truth of a guard extending to a given width:

guard width	share of all real REM inside it	subjects affected
45 min	0.36 %	1 of 31
90 min	6.85 %	15 of 31

60 min sits inside the defensible band. Because the penalty is graded rather than a cliff it is already down to <= 0.75 log-odds (x0.47, against x0.05 at onset) across 45-60 min, so a genuine sleep-onset REM period late in the window is held back rather than suppressed. 60 min also stops clear of the ~70-100 min population first-REM latency, so the ramp is spent before real REM is expected.

This matters for the population #930 flagged as INFERRED, not measured: REM latency shortens with age, and a minority of people show sleep-onset REM periods. A graded, bounded, soft ramp degrades for them instead of cliff-edging, but I have no data on that group and am not claiming otherwise.

---

Before/after on real nights — kappa and stage fractions

Replayed with Tools/SleepBench's reader over a copy of a real device database: 36 sessions, of which 15 carry a stagelock cursor (human-authored hypnograms via the cloud edit path — not merely userEdited, which re-derives stages machine-side over a human-chosen window). 9,163 reference epochs.

The reference set is the stage-locked rows precisely because that set comes from cursors and therefore does not move when the recipe changes. (SleepBench's "byte-exact replay of the current V2" exclusion is version-dependent by construction — a night can leave the exclusion just because the recipe changed, silently swapping the denominator underneath a before/after. That happened to me on the first pass: 11 nights before, 12 after.)

kappa — essentially flat, as predicted

	before	after
4-class accuracy	78.2 %	78.2 %
4-class kappa	0.691	0.689
sleep/wake kappa	0.583	0.582

Per-stage fraction calibration — the guard kappa does not provide

#437 reverted #348 with the words "kappa doesn't guard stage-fraction calibration — a systematic wake-fraction bias sails through it." A cliff term is exactly the shape that moves stage fractions without moving kappa, so:

Per-night bias vs the human reference (predicted - truth, percentage points; n = 15):

stage	before	after
wake	-7.26	-7.13	improves
light	-7.54	-6.10	improves
deep	+6.65	+6.65	unchanged
rem	+8.15	+6.57	improves

Total absolute bias 29.60 -> 26.45 pp. MAE improves on light (8.52 -> 7.41) and rem (9.01 -> 8.33), is unchanged on deep, and worsens 0.11 pp on wake (8.01 -> 8.12).

Healthy-sleeper stratum (in-bed >= 5 h, n = 20) — the cohort #348 broke:

stage	before	after	delta
wake	9.40 %	9.43 %	+0.03 pp
light	38.50 %	38.91 %	+0.41 pp
deep	22.09 %	22.09 %	0.00 pp
rem	30.00 %	29.58 %	-0.42 pp

For scale, the #348 field symptom was a healthy night moving wake 6 % -> 23 % (~17 pp). Nothing here moves more than 0.42 pp, and wake moves 0.03 pp.

Deep is byte-identical on all 36 nights (max |delta deep| = 0.00 pp), which is the direct check that the deep term was not disturbed.

Where the change actually lands

12 of 36 nights change at all; 24 are byte-identical. The effect is monotone in session length — i.e. it lands on precisely the sessions the fractional guard was mis-scaling:

stratum	nights	changed	mean delta rem	mean delta wake	max abs delta wake
< 2 h in bed	4	4	-20.90 pp	+2.12 pp	4.90 pp
2-5 h in bed	12	4	-2.37 pp	+0.15 pp	1.60 pp
>= 5 h in bed	20	4	-0.43 pp	+0.03 pp	0.20 pp

First-REM latency (the quantity this term controls), all 36 nights: median 72.2 -> 83.2 min, p10 37.0 -> 58.0, min 10.0 -> 43.0 min. The sub-15-minute sleep-onset-REM calls are gone.

I want to be explicit about the largest behavioural change, because it is the one worth arguing with: four sessions of 61-81 min drop from 11.7-35.5 % REM to 3.7-5.7 %. Under a 60-minute guard, a nap shorter than an hour is suppressed for most of its length. I believe that is the physiologically right prior — REM in a sub-hour nap is uncommon outside REM rebound — and the guard remains soft, which is why those nights still call 3.7-5.7 % REM rather than zero. But it is a real change in what a nap looks like in the app, it is by design, and if anyone thinks a shorter M0 is warranted for naps specifically, 45 min is equally defensible on the measured cost table above.

---

Plumbing

Epoch gains minutesSinceOnset, and stageEpochs becomes two passes: stage once with the guard disabled (cyclePrior(c, .infinity)), take the first sustained non-wake run as onset, then apply the guard and re-run Viterbi. The onset rule is 5 minutes sustained sleep (10 epochs on the 30 s grid), measured against PSG onset on sleep-accel at bias -3.8 min, MAE 7.4 min (n = 31).

Only the guard differs between the passes — every emission term, z-score and percentile is computed once and reused — so the cost is one extra Viterbi over an already-built lattice, not a second featurisation, and stageSession memoizes the result anyway.

Two deliberate degradation choices:

• No sustained run (a nap below the rule, an all-wake window) -> the origin falls back to the window start, which is exactly the origin the shipped c-based guard used.
• The guard is clamped to [0, K], so a pre-onset epoch cannot be penalised harder than onset itself. SleepStagerV2.cyclePrior: the REM step is a fraction of session length, so the REM-latency guard varies 7-85 min across one user's nights #930's follow-up comment noted that the origin inherits detection error and that [sleep] WHOOP 4.0 over-stages the low-motion pre-onset stretch as sleep (detected onset lands too early) #271 can place a window start ~4 h early on WHOOP 4.0; without the clamp such an epoch would take an unbounded penalty.

---

Tests

The regression test the previous shape could not express — a 10-hour night and a 3-hour fragment must receive the same guard at the same minute after onset. Under c < 0.12 they disagree by construction: 30 min in is c = 0.05 (fully suppressed) on the long night and c = 0.167 (not suppressed at all) on the fragment. The test isolates the guard from the 1.0 * c ramp (which legitimately differs) by subtracting the ramp back out, and there is an end-to-end twin that stages the same streams under both window lengths and asserts the first 60 minutes agree epoch-for-epoch.

Also added, in both languages: guard shape / clamp / monotonicity with the constants pinned across platforms, and the sustained-onset rule (9 epochs must not qualify, 10 must, a brief run before a sustained one must not be mistaken for onset).

suite	result
swift test (Packages/StrandAnalytics, on this branch)	1171 passed, 0 failed
./gradlew testFullDebugUnitTest	3213 passed, 0 failed, 5 skipped (392 suites)

Android counts read from app/build/test-results/testFullDebugUnitTest/*.xml, not the wrapper exit code. android.yml is disabled so CI does not run Kotlin tests on PRs — local verification is the only gate, and I ran it against JDK 17.

Both frozen goldens are unchanged, in Swift and Kotlin — the pinned end-to-end recipe shape and the Swift/Kotlin parity it proves both survive this change, which is the cheapest evidence that the two implementations still agree epoch-for-epoch.

Per the parity contract the Kotlin twin changes in this same PR, including the constants; remLatencyPenalty / remLatencyMinutes / cyclePrior / sustainedSleepOnset are internal on Android so the parity test can pin them, matching the Swift visibility.

---

Known, and NOT addressed here

Two real defects this work surfaced that are not caused by this term and are tracked separately:

1. Median first-REM latency runs ~54 min late against PSG — 142 min predicted vs 88.5 min truth. Removing the step gives 141, so the guard is not the cause.
2. Deep is under-called 2-3x — 4.7-6.2 % predicted vs 14.8 % truth. Visible in the table above as the +6.65 pp deep bias, unchanged by this PR because the deep term is untouched.

Neither is in scope; fixing them inside a units correction would make both un-reviewable.

Caveats

• The sleep-accel figures are CONFIRMED measurements at the stated sample sizes (n = 31 subjects, LOSO). The device-replay figures are one wearer, one strap family (WHOOP 5), 36 sessions, 15 human-authored references — descriptive of that database, not population values. The structural claims (guard width scaling with session length, deep untouched, the monotone-in-duration effect) are properties of the code.
• The < 2 h stratum is 4 nights. The mean -20.9 pp REM shift there is the direction the design intends, but the magnitude rests on very little data.
• The second-order concern about older wearers and sleep-onset-REM populations is INFERRED from the literature, not measured — I have no data on it. It argues for a graded shape over a cliff, which is what this does; it does not justify any particular M0.

Refs #930. Prior art on changing V2's staging constants: #348 and its #437 revert — the "kappa doesn't guard stage-fraction calibration" line from #437 is why the stage-fraction and healthy-stratum tables above exist at all.

[ryanbr]

Checked the code rather than re-reading the evidence, since the evidence is the part that already
argues itself.

The twins are exact. minOf(1.0, maxOf(0.0, …)) against min(1.0, max(0.0, …)), the same clamp,
the same constants, and sustainedSleepOnset with identical index arithmetic — `i - onsetSustainedEpochs

• 1is the run's first epoch, correct on both.Double.POSITIVE_INFINITYand.infinityboth driveremLatencyGuard` to exactly 0, so pass 1 is genuinely unguarded on each platform rather than
  approximately so. Pass 2 subtracts only the guard; every other emission term is untouched.

Goldens untouched is the strongest single line in this PR — it is the cheapest available proof the
two implementations still agree epoch-for-epoch after a recipe change. Worth being clear about what it
does not prove: the fixture night is evidently one of the 24 that do not move, so the goldens attest that
nothing ELSE shifted, not that the new path is right. That rests on the new tests and the replay.

The MotionCorroboratedWake edits are constructor updates in both languages, no assertions weakened.

One correction to the description, in your favour. android.yml is no longer disabled — it was
turned back on earlier today, and build-and-test in this PR's green checks IS the Android job. Your
3213 Kotlin tests ran in CI, not only locally. The caveat can go.

Two things worth saying out loud, neither blocking.

Onset is located by a pass that is more REM-permissive than anything that ships — pass 1 has no guard at
all, where the incumbent had -3.0 below c < 0.12. Only awake-vs-not affects the onset rule, so this
only matters where a marginal epoch flips awake→REM and pulls onset earlier; that makes the 60-minute
window start earlier and therefore expire earlier, so it is mildly self-correcting rather than
self-reinforcing. Defensible, and worth a sentence in the file saying the origin is measured under a
prior that never ships.

Epoch.minutesSinceOnset holds minutes since the WINDOW START until stageEpochs re-bases it. The doc
comment says so plainly, but the field name asserts otherwise at every other read site. Given that this
whole issue started with constants a reader could not tell fit from hand-picked, a name that means what
it says is worth something — minutesSinceWindowStart would cost one rename.

The decision that is actually yours, not mine: four sessions of 61-81 min drop from 11.7-35.5 % REM
to 3.7-5.7 %. Under a 60-minute guard a sub-hour nap is suppressed for most of its length. That is the
physiologically right prior and the guard stays soft, so those nights still call 3.7-5.7 % rather than
zero — but it is a visible change to what a nap looks like, it rests on 4 nights, and you note 45 min is
equally defensible on your own cost table. Everything else here moves under half a percentage point.

Approving on the engineering. The units fix is correct, the shape is right, the parity holds, and the
refusal to claim an accuracy win it cannot demonstrate is the reason the rest of it is credible.