Fix remaining health review issues and document ring clock skew

This commit is contained in:
James Babcock committed 2026-09-17 21:21:05 -07:00
1 parent 7677dd254e
commit 27a5fe47ef
10 files changed
+323 -191

No files matched your search

+1 -5
View File
@@ -8,15 +8,11 @@ import { Application } from '@nativescript/core'
import { registerShareIntentHandler } from './native/share-intents'
import { installNativeUserAgent } from './util/http'
import { registerPhoneRotation } from './native/phone-rotation'
installNativeUserAgent()
registerShareIntentHandler()
registerPhoneRotation()
import { startLiveHealthSync, startAlignedRingPull } from './health/health-live'
installNativeUserAgent()
registerShareIntentHandler()
registerPhoneRotation()
// Ring health records live only in the communicator's memory until something
// stores them. Both health surfaces store on open, but a pull that lands while
+2 -3
View File
@@ -28,7 +28,7 @@ import {
type InProcessAppOptions,
type InProcessWindow,
} from "../../ui/shell/in-process-window";
import { dailySummary, hypnogram, rollupSeries, type DailySummary } from "../../health/health-derive";
import { dailySummary, dailyHypnogram, rollupSeries, type DailySummary } from "../../health/health-derive";
import {
drawGlancePage,
GLANCE_PAGES,
@@ -114,8 +114,7 @@ class HealthLayer implements Layer {
});
}
this.hourly = hourly;
const night = sessions.find((session) => session.dayStartMs === today);
this.stageBands = night ? hypnogram(night) : [];
this.stageBands = dailyHypnogram(sessions, today);
this.fixture = isFixtureData();
} catch (error) {
console.warn("health glance reload failed", error);
+40 -9
View File
@@ -165,9 +165,7 @@ export function dailySummary(
const inDay = samples.filter(
(sample) => sample.startMs >= dayStartMs && sample.startMs < dayEndMs,
);
const night = sleepSessions
.filter((session) => session.dayStartMs === dayStartMs)
.sort((a, b) => b.totalSec - a.totalSec)[0];
const nights = sleepSessions.filter((session) => session.dayStartMs === dayStartMs);
return {
dayStartMs,
steps: Math.round(sumOf(inDay, "steps")),
@@ -175,7 +173,7 @@ export function dailySummary(
heartRate: summarise(inDay, "heartRate"),
spo2: summarise(inDay, "spo2"),
hrv: summarise(inDay, "hrv"),
sleep: night ? sleepSummary(night) : null,
sleep: combinedSleepSummary(nights),
};
}
@@ -250,6 +248,21 @@ export function sleepSummary(session: SleepSession): SleepSummary {
};
}
/** Every recorded block attributed to the day contributes to its headline. */
export function combinedSleepSummary(sessions: readonly SleepSession[]): SleepSummary | null {
if (sessions.length === 0) return null;
const combined: SleepSession = {
...sessions[0], totalSec: 0, wakeSec: 0, remSec: 0, lightSec: 0, deepSec: 0,
timeResolved: sessions.every((session) => session.timeResolved),
};
for (const session of sessions) {
for (const field of ["totalSec", "wakeSec", "remSec", "lightSec", "deepSec"] as const) {
combined[field] += Math.max(0, session[field]);
}
}
return sleepSummary(combined);
}
/**
* One stage's seconds, from the summary's own bands.
*
@@ -272,11 +285,7 @@ export function stageSeconds(stage: SleepStageName, summary: SleepSummary): numb
* night with no record comes back as `hasData: false` at its real position
* rather than shifting every later night one column left.
*
* Two sessions attributed to the same day are SUMMED rather than the longest
* winning. That differs from `dailySummary`, which picks the longest because it
* is answering "how did you sleep last night" with one headline number; here
* the column is the day's total time in each stage, and dropping a nap would
* make the bar disagree with the sleep total shown beside it.
* Sessions attributed to the same day are summed, as in `dailySummary`.
*/
export function sleepNights(
sessions: readonly SleepSession[],
@@ -336,6 +345,28 @@ export function hypnogram(session: SleepSession): { stage: SleepStageName | null
}));
}
/** Chronological blocks, with unrecorded intervals left as unknown gaps. */
export function dailyHypnogram(sessions: readonly SleepSession[], dayStartMs: number): ReturnType<typeof hypnogram> {
const result: ReturnType<typeof hypnogram> = [];
let previousEnd: number | null = null;
for (const session of sessions.filter((s) => s.dayStartMs === dayStartMs)
.sort((a, b) => a.startMs - b.startMs)) {
if (previousEnd !== null && session.timeResolved && session.startMs > previousEnd) {
result.push({ stage: null, seconds: (session.startMs - previousEnd) / 1000 });
}
const bands = hypnogram(session);
result.push(...bands);
// A session without stage data still occupies its recorded interval.
const covered = bands.reduce((total, band) => total + band.seconds, 0);
const duration = session.timeResolved
? Math.max(0, (session.endMs - session.startMs) / 1000)
: session.totalSec + session.wakeSec;
if (duration > covered) result.push({ stage: null, seconds: duration - covered });
previousEnd = session.timeResolved ? Math.max(previousEnd ?? 0, session.endMs) : null;
}
return result;
}
/**
* Date formatting, done by hand.
*
+10 -54
View File
@@ -77,66 +77,22 @@ function activeCommunicator(): any {
}
/**
* The ring timestamps in a frame 4 hours ahead of real time, and that is our
* own doing: the handshake sets its clock to `now + 14400s`, because that is
* what a real Even write carries (verified against six of them). Even's app
* evidently subtracts the same offset on the way back out. We were not, so
* every hourly sample landed 4 hours in the future.
*
* MEASURED, not theorised. Stored samples read 09:00/10:00/11:00 local while
* the actual time was 07:15; minus four hours gives 05:00/06:00/07:00, which
* is exactly right for a ring that had just reported the current hour.
*
* ⚠ This value is PAIRED with the offset in `sendRingHandshake()`. They must
* move together.
*
* Both were hardcoded to 14400. As of 2026-09-12 both COMPUTE it: 14400 was
* only ever right because every capture behind this work was taken in EDT,
* where 14400s is the magnitude of the UTC offset. Computing it is identical
* today and survives DST.
*
* ⚠ MIND THE SIGN. The quantity is "how far AHEAD of real time the ring's clock
* runs", which is the magnitude of a west-of-UTC offset — positive 14400 in
* EDT. `getTimezoneOffset()` is already minutes WEST of UTC (+240 in EDT), so
* it is used as-is, NOT negated. Java's `TimeZone.getOffset()` uses the
* opposite convention and is negated there; the two agree on +14400.
*
* Worth recording because the first cut of this change got the sign backwards
* on both sides at once — consistently, so they stayed "paired", and still
* wrong by 8 hours. Only the handshake's own assertion log caught it.
*
* Note this direction is the OPPOSITE of the "ring stores naive local time"
* hypothesis (which predicts `epoch + utc_offset`, i.e. 4h behind). Measured
* behaviour is 4h ahead. The hypothesis is unconfirmed; the measurement rules.
* Legacy compensation for the incorrect extra timezone shift sent by the
* handshake. This is not a ring protocol requirement. Fresh HR timestamps on
* the PDT test ring run seven hours ahead, but older values and daily anchors
* do not share that shift. Keep this paired with the existing handshake until
* a controlled UTC migration; do not apply it retrospectively to raw history.
* See notes/ring-health-live-validation.md.
*/
function ringClockOffsetMs(atMs: number): number {
return new Date(atMs).getTimezoneOffset() * 60 * 1000;
}
/**
* Sleep timestamps need TWICE the correction the hourly samples need.
*
* ⚠ EMPIRICAL, AND THE MECHANISM IS UNEXPLAINED. Do not read a story into the
* factor of 2. The last time this file invented a tidy explanation for a ring
* clock quirk ("the ring stores naive local time") it was falsified the next
* day, which is why the hourly comment above ends with "the measurement rules".
* The same applies here, more so: nothing about a sleep record is known to
* differ from an hourly one in how it is stamped, and yet the correction does.
*
* The evidence, 2026-09-12, the first real sleep record off the hardware:
* `start_ts` decodes raw to 10:21:01 EDT. Chris confirmed the true window two
* independent ways - he slept "straight through from around 1:30 AM to 9:30 AM",
* and separately reported seeing only the first block with "another 4 or so
* hours after that". Under -4h the block is 06:21 -> 09:25, which puts the
* missing time BEFORE it and contradicts what the device showed. Under -8h it
* is 02:21 -> 05:25, leaving 05:25 -> 09:30 (4h05m) missing AFTER it, which is
* what he saw.
*
* Expressed as twice `ringClockOffsetMs` rather than a fresh 28800 so the
* November DST change moves the hourly correction and this one together. Like
* the hourly path it is evaluated at the RAW instant, so within ~8h of a DST
* switch it can pick the wrong side by an hour - the same caveat, deliberately
* kept identical rather than special-cased here.
* Inherited sleep-specific heuristic, still unvalidated on this ring (no sleep
* DATA page received yet). Firmware describes UTC timestamps, not a double
* timezone offset. Remove alongside the controlled clock migration, then
* validate against a recorded night; it is not evidence of correct placement.
*/
function sleepClockOffsetMs(atMs: number): number {
return 2 * ringClockOffsetMs(atMs);