[pipiche38]

Fixes #1716.

A sleep session's stage timeline is supposed to TILE its span. SleepStageTotals says so in as many
words — "the segment stages noop stores (which TILE the window, last segment clamped to the wake), Σ
stage minutes equals the clock span … would diverge only for malformed non-tiling stages" — and every
consumer downstream is written as though it holds.

One producer breaks it. A device-PROVIDED hypnogram is assembled from records that can arrive
INCOMPLETE, and OuraSleepSessionMapping merges only CONTIGUOUS codes, so a sleep-phase page that
never arrived leaves a hole in stagesJSON while startTs/endTs still span the whole night. The
row that comes out looks well-formed: non-empty, many segments, a plausible efficiency. It just
describes a fraction of the night it claims.

What it costs

31 consecutive nights on one ring, 22 of them with a WHOOP strap worn the same night as ground truth.

night	span	covered	cov%	stored TST	eff	WHOOP TST	TST err
2026-07-30	52	52	100%	44	86%	492	−448
2026-08-01	510	510	100%	81	16%	458	−377
2026-08-11	520	520	100%	186	36%	506	−320
2026-08-12	520	442	85%	328	74%	444	−116
2026-08-13	130	62	48%	28	46%	474	−446
2026-08-15	390	156	40%	64	41%	483	−418
2026-08-16	368	286	78%	100	35%	445	−344
2026-08-17	485	405	83%	346	85%	448	−102
2026-08-18	601	140	23%	70	50%	494	−424
2026-08-21	534	498	93%	416	84%	—	—
2026-08-24	550	506	92%	411	81%	—	—

Minutes throughout. 9 of 31 nights affected; mean stored-TST error −328 min across the seven with
strap truth. Healthy nights sit at −18…−54 min, which is just the onset/offset difference between two
devices on one wrist.

2026-08-18 is the clean example: 70 minutes of sleep at 50% efficiency with 3 minutes of REM,
against a strap that recorded 494 minutes at 85%. Those numbers feed the sleep-debt ledger, the
Rest composite (hence Charge) and the baselines, at full weight.

Why nothing caught it

• The merge's richness rule is a presence test. SleepMerge.hasStages asks only whether the
  payload is non-empty and not "[]". The holed row carries 21 segments, so it passes and wins its
  day. The rule guards against a stage-less import; it has no concept of a stage-holed one.
• gravitySparse is inert here. SleepStager.isGravitySparse returns false when
  grav.count < 2, and the Oura path banks no gravity at all — so the Sleep: Whoop vs Noop #345 guard never fires on any
  ring night, not just this one.
• The #H9 restorative floor needs efficiency >= 0.85. This night reads 0.50, so it is skipped.
  H9 also could not have caught it in principle: the part that did arrive has an ordinary
  restorative share.

So the night was reported .solid.

The change

The missing quantity turns out not to be a new measurement at all — it is a ratio of two numbers
already stored (Σ segment durations ÷ endTs − startTs). HypnogramCoverage derives it on read.
Nothing is persisted and there is no migration, which also means it applies retroactively to nights
already in the database rather than only to future ones.

1. Richness becomes a RANK. SleepMerge / WhoopRepository.mergeSleepRichness:

rank	meaning
2	stages covering the span they claim
1	stages present but holed
0	no stages

and the computed day wins only when it out-ranks the import. Collapsing 1 and 0 together gives
back the original presence rule exactly, so this is a strict generalisation — every case #240/#241
decided, it still decides the same way. The only pair whose outcome changes is the one the old rule
could not express: a holed import against a complete computed night.

This shape was not the first attempt. Swapping hasStages for a hasUsableStages that also requires
coverage, applied symmetrically, regresses #240 — a holed computed night must still rescue the
day from a stage-less import, but under a symmetric test both sides read "not usable" and the
stage-less import wins, blanking the night. The existing suite caught it.

2. ScoreConfidence.rest gains a third downgrade clause on coverage, beside gravitySparse and
the H9 floor — a new clause in the existing mechanism, not a new mechanism.

3. AnalyticsEngine sums coverage off the already-decoded segments (no JSON re-parse) and passes
it. It is accumulated separately from inBedS, because that one later absorbs the inter-fragment gap
(#777/#705) and those are different quantities: a bridged out-of-bed gap is known-awake time between
two fragments, whereas a hole INSIDE a fragment is time we never observed.

Threshold minCoverage = 0.95. The observed nights separate cleanly — healthy 99–100%, broken 23–93% —
so the gate sits in empty space rather than balanced on the edge of the data.

What it deliberately does not do

• It does not count uncovered time as awake. We do not know what happened there. Asserting wake
  would be the same overreach as the current behaviour, pointed the other way. The guard reports only
  how much of the night was observed.
• Both guards fail OPEN. Coverage is nil for a payload it cannot measure, and nil means "not
  measured", never "measured badly". That is what keeps this away from WHOOP / Apple / Health-Connect
  imports: their minute-dict shape carries no timestamps, so it is never judged holed and they are
  scored on presence exactly as before.
• It recovers no sleep. The pages never arrived — that is the overnight link/drain problem, tracked
  separately. This stops NOOP asserting a night it did not observe.
• It changes no score. Confidence-only, and no stages are invented.

Not in this PR

The same investigation found a second defect at AnalyticsEngine's main-group loop: in-bed comes from
the clock span while TST comes from the segments, so Rest.composite receives an inconsistent
pair (tst 70 min against in-bed 601 min) on exactly these nights. Fixing it means taking in-bed from
the segments — which changes stored daily numbers, so per the one-concern rule it belongs in its own PR
with its own recompute thinking. Not here.

Two of the nine affected nights (2026-08-01, 2026-08-11) tile 100% but call most of the night "wake".
That is a different and unattributed failure mode — 0xFF decodes to four codes of 0b11 = awake
and MIN_TRAILING_UNWRITTEN = 6 only suppresses a trailing run of ≥ 6 bytes, which is a candidate,
not a cause. Both nights predate the raw sidecars, so the wire bytes are gone and it cannot be
confirmed. Out of scope here; noted so it is not mistaken for something this PR handles.

Verification

Pure and cross-platform throughout — no strap, no CoreBluetooth, no BLE path touched.

gate	result
swift test WhoopStore	441 pass
swift test StrandAnalytics	1636 pass
./gradlew testFullDebugUnitTest	4739 pass, 2 failures (below)
macOS app target build	succeeds
StrandTests under xcodebuild … test	passes
iOS NOOPiOS target build	succeeds
Tools/doc_comment_lint.py	OK
Tools/i18n_audit.py --ci	OK

The two Android failures are RecoveryDriversTest float rounding (expected:<-0.5> but was:<-0.4999999999999929>), confirmed failing identically on a clean tree at this same base before
any of these changes — unrelated to sleep, and not the known locale-sensitive set (those pass under
-Duser.language=en; these still fail).

App targets were built locally because app-build.yml is disabled by default, so nothing in CI covers
them.

Parity is pinned by oracle, not by eye. HypnogramCoverageTest embeds the verbatim stdout of the
Swift twin compiled standalone (swiftc -O) across the input space that matters: tiling, an interior
hole, the measured night, the gate boundary from both sides and exactly on it, overlap/overhang,
every unmeasurable payload shape, and degenerate spans. The boundary row earns its place — 950/1000
prints as 0.94999999999999996, which is the same double the 0.95 literal denotes, so it is not
holed. Reading the two implementations side by side could not have settled that.

New tests: HypnogramCoverageTests / HypnogramCoverageTest (both platforms), plus coverage-rank
cases in SleepMergeTests / MergeSleepLocalDayTest and coverage cases in AnalyticsEngineTests /
ChargeEffortRestScoringTest. The confidence tests pin the real night twice: once asserting it reads
.solid without coverage (the bug), once .building with it.

[ryanbr]

@pipiche38 — merged, and the follow-up in #1721 landed the parity and documentation edges. One design question came out of the review that is yours to settle rather than mine, so I pinned the current behaviour by test instead of changing it.

The gate reaches the Xiaomi Band importer. The PR describes imports as out of scope because their minute-dict shape carries no timestamps to compare against a span. That holds for the WHOOP CSV, Apple and Health Connect. XiaomiBandImporter is the exception: it emits real {start,end,stage} segments from the vendor's items array, and takes startTs/endTs from bedtime/wake_up_time (falling back to device_bedtime/out_bed_timestamp) — fields that are independent of the items it builds those segments from. So a Xiaomi night is measured like any device hypnogram, and one whose items do not reach its own bed/wake bounds reads as holed.

That may well be correct — such a night genuinely is only partly described, which is the argument the PR makes — but it is a behaviour change for that importer that neither of us has validated against a real export, and it lands at both call sites: rank 1 at the merge, and a .building Rest.

Two things I could not answer from the code:

1. Do Xiaomi's items tile bedtime → wake_up_time by construction? stageName maps state 1 and 5 to wake, so awake spans are represented, which suggests they might. But if the vendor's bed/wake fields bracket the items even slightly — bed recorded at "got into bed" while the first item starts at sleep detection — every Xiaomi night sits just under 1.0, and some fraction lands under 0.95 with nothing distinguishing them from a genuinely holed night.

2. If they routinely do not tile, is 0.95 the right threshold for that source? Your 0.95 sits in empty space for Oura, where the split is 99–100% against 23–93%. There is no reason that separation transfers to a different vendor's segment semantics.

If you have a Mi Fitness export to hand, the coverage distribution across its nights would answer both at once — the same way the ring data settled the threshold. If Xiaomi turns out to need different treatment, the options are a per-source threshold or exempting it, and either is a small change on top of what is there now.

No action needed if you are happy for Xiaomi to be judged on the same rule. The behaviour is pinned by an oracle row and the module doc now states it outright, so whichever way it goes it will not be discovered by surprise.