Skip to content

Accuracy check: compare the ring with another device via Health Connect - #30

Merged
gabrielbr merged 9 commits into
mainfrom
claude/brave-cerf-2jew36
Oct 21, 2026
Merged

gabrielbr merged 9 commits into
mainfrom
claude/brave-cerf-2jew36

Conversation

@gabrielbr

Copy link
Copy Markdown
Owner

Adds Settings → Accuracy check. You wear the ring and a device you trust (e.g. a Huawei watch through Health Sync) for a few days. PulseLoop reads that device's Health Connect records, reports where the ring agrees or falls short, and can correct a consistent bias. Design and "As built" notes are in docs/accuracy-check-plan.md, and the rules most likely to be undone later are in a new AGENTS.md section.

What's in it, by phase

  • Phase 0 — survey. Separate read permissions for 8 data types. The scan lists, per app writing to Health Connect: what it writes, how often, how late it arrives, and which device it names. Health Sync is labelled as a bridge app. A heart-rate echo check catches PulseLoop's own exports coming back through a bridge.
  • Phase 1 — running a check. The check runs 3, 5, 7 or 14 days. It ends on schedule (with a notification), early by hand, or the moment a different ring is paired.
    • While it runs, only the types the reference device writes are held back from the export. A held-back record is filtered by its data time, and the export's watermark still advances past it.
    • So Skip these days (the default) needs no undo, and a record from the check window that is updated later stays out of Health Connect.
    • Export them too rewinds the affected watermarks under the export's pass mutex.
    • Room v36 adds 4 tables and 1 column. The migration SQL was checked against Room's generated schema. All of it rides the archive.
  • Phases 2–3 — comparison and report. Steps, distance, active calories, time asleep, fell-asleep and woke-up times, sleep stages, heart rate at rest and when active, resting HR, SpO₂ and HRV.
    • A day is scored only once the reference has delivered it (or 24 h after it ends), and a day either device wasn't worn is left out.
    • Verdicts are Agrees / Consistently high or low / Inconsistent / Not enough data. Agreement bands are editable per metric.
    • The report lists the metrics outside their band worst first, and has a Share text with no individual readings.
    • The reference's readings are never stored; only per-day aggregates are.
  • Phase 4 + follow-up — corrections. Offered only after a "Consistently high/low" verdict: a scale factor for steps and distance, an offset for HR at rest and active, resting HR, SpO₂ and time asleep.
    • Applied at read time on Today, Vitals, Sleep, Activity, the widgets, the coach and the live workout readout. Every corrected figure is labelled.
    • They also feed the HR zones, resting baseline and calorie estimate, through copies kept separate from the raw ones.
    • Stored rows, the Health Connect export and Strava stay raw. Corrections are saved per ring.

Testing

  • ./gradlew :app:testDebugUnitTest: 1,752 tests ran and 3 failed. The 3 failures (ResponsesHttpTest, MealJournalTest) also fail on the base commit and are unrelated to this change.
  • 62 new tests cover the survey, export pause, comparison, verdicts, report wording and corrections.
  • Not run on a device or with real Health Connect data. The first real check with the Huawei/Health Sync setup still has to confirm the Health Sync details listed under Open questions in the plan doc.

Generated by Claude Code

Compare the ring against a trusted device's Health Connect records for a
few days, pause the export meanwhile, report bias vs noise per metric, and
offer read-time corrections only where the bias is consistent.
… ring changes

Corrections stay out of Health Connect but feed baseline, zones and
calorie estimates via adjusted copies. The export pause covers only the
types the reference writes. Adds the Health Sync bridge caveats (origin
label, echo risk, lag) and what happens when the user changes rings.
Settings → Accuracy check asks for its own Health Connect read permissions
(steps, distance, active calories, HR, resting HR, sleep, SpO2, HRV) and
scans the last 7 days. Per source app and type it shows record/sample
counts, median cadence, median delivery delay (lastModifiedTime - endTime,
i.e. a bridge's sync lag), Metadata.device, and sleep stage types. Health
Sync is labelled as a bridge, and an echo check flags a source whose HR
matches the ring's own to the second and beat (a two-way bridge sending
PulseLoop's export back). Copy summary gives counts and timings, no
readings. Nothing is stored; no check runs yet.

The export's reconcile already filters to its own write set, so these
grants don't register as export grants (pinned in ReferenceSurveyTest).
The rationale screen now describes both read paths.
…nnect exports

A check is started from a source card in Settings -> Accuracy check, runs
3/5/7/14 days, and ends on time (one-shot worker plus a 6-hourly backstop
and a report-ready notification), early by hand, or the moment a different
ring is paired (AccuracyRingWatcher; ring data carries no device id, so it
can't be split later).

While it runs, the export holds back only the record types the reference
writes (ExportUnit: steps, distance and active calories separately), by
data time: a held-back record is dropped from the pass and its watermark
still advances past it, like a never-exportable row. So the default resume
choice, Skip these days, needs nothing but closing the window, and a
window record updated later (a re-synced night) stays held back. Export
them too drops the exclusion and rewinds the affected watermarks to where
holding back began (rewindWatermarks: never forward, never past a
new-only user's consent), under the export's pass mutex. The pause set
grows when the reference starts writing a type mid-check, from that
type's first record.

Room v36: accuracy_checks, accuracy_paused_units, accuracy_check_days,
accuracy_corrections, and activity_daily.estimatedActiveCaloriesAdjusted
for Phase 4; migration SQL checked against Room's generated schema. All of
it rides the archive, since it holds the export exclusions.
…port it

AccuracyScorer reads the reference's records for the check window
(origin-filtered, foreground) and reduces them to per-day aggregates in
accuracy_check_days; the reference's readings are never stored.

Compared: steps, distance, active calories (whole local days inside the
window, skipping days either device clearly wasn't worn); time asleep,
fell-asleep and woke-up times, and minute-by-minute stage agreement per
waking day; heart rate paired sample by sample, split at rest (asleep, or
a quiet 15-min bucket) vs active (a busy bucket or a workout), with the
pairing window widened for a sparse reference like a bridge app; resting
HR and HRV per night; SpO2 paired within five minutes. A day is scored
once the reference has delivered past its end, or 24 h after it, so a
bridge's sync lag doesn't read as the ring overcounting.

AccuracyComparison.summarize separates bias from noise: Agrees, Consist-
ently high/low (average outside the band, >=80% of days the same way,
day-to-day wobble smaller than the bias; only these offer a correction)
or Inconsistent. Bands are editable per metric and verdicts recompute from
the stored rows. The report lists metrics outside their band worst first,
warns when the reference's HR echoes the ring's own, and says 'differs
from <reference>', not 'is wrong by'.
A metric the report calls consistently high or low offers its fitted
correction (steps and distance: a scale factor; heart rate at rest and
when active, resting HR, SpO2 and time asleep: an offset), adjustable
with a slider before it's saved. Inconsistent metrics offer none, and
sleep timing, stages, HRV and calories stay report-only.

Corrections never touch stored rows (the ring re-sends its history
anyway) and never reach Health Connect; they're applied in the
ViewModels, so Today, Vitals and its detail charts, Sleep, Activity and
the widgets built from the same state all show the same figures, each
screen with an 'Adjusted by your accuracy check' caption. A single heart
rate sample is split rest/active at Flex-HR, the calorie estimator's own
threshold. Derived figures follow: the HR zones sit on the baseline plus
the at-rest offset (an offset moves a percentile by itself, so nothing is
recomputed), and the calorie estimator writes a corrected copy beside the
raw one (estimatedActiveCaloriesAdjusted); the app shows the copy, Health
Connect still gets the raw column. Changing a correction re-runs 90 days
of estimates without bumping updatedAt, so the export doesn't re-read
them. A steps correction supersedes the phone step calibration rather
than stacking on it.

Corrections belong to one ring (keyed by BLE address): a different ring
starts with none, the old ring's come back if it's re-paired, and a
correction fitted 90+ days ago or on other firmware is flagged for a
fresh check.
Share on the report sends the verdicts and headline differences with the
ring's model and firmware, for issue reports; aggregates only, no day
values or readings, for the same reason the diagnostics export has none.

docs/accuracy-check-plan.md gains an As built section recording where
the code differs from the plan (held-back exports filtered by data time
rather than by holding the watermark; no charts in the report; onset/wake
report-only; Flex-HR split for heart-rate corrections; what stays raw).
AGENTS.md gets the rules most likely to be undone by a later cleanup.
… workout

The two gaps left by Phase 4.

Widgets: the steps and sleep tiles read raw rows while the heart-rate and
SpO2 tiles (via VitalsViewModel.buildState) were corrected; all of them
now use the same corrections, and each corrected tile adds '· adjusted'
to its header. The payloads carry an adjusted flag that defaults to false,
so snapshots written before it still decode.

Coach: the context builders, the summary and notification contexts and
the data tools read steps, distance, sleep, heart rate and SpO2 through
the corrections, and the data-quality notes tell it which figures are
adjusted, so it neither presents them as raw readings nor corrects them
again.

Live workout: the bpm readout and its zone are corrected and labelled on
the record screen, as are a finished workout's displayed HR and SpO2
stats. What the workout stores stays raw: Health Connect and Strava get
it.
@gabrielbr
gabrielbr merged commit 2236406 into main Oct 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants