From c8a890f57ee6a6d2c15e770a8177c6346c2cb123 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 13:58:49 +0000 Subject: [PATCH 1/9] docs: plan an accuracy check against another device via Health Connect 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. --- docs/accuracy-check-plan.md | 260 ++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/accuracy-check-plan.md diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md new file mode 100644 index 00000000..f5ef081d --- /dev/null +++ b/docs/accuracy-check-plan.md @@ -0,0 +1,260 @@ +# Accuracy check — compare the ring against another device via Health Connect + +Status: **plan, nothing implemented.** Date: 2026-10-21. + +## The idea + +People online often say cheap rings aren't reliable. PulseLoop can answer that for the user's +own ring rather than in general. The user wears the ring **and** a device they trust (Fitbit, +Pixel Watch, Galaxy Watch, Garmin, anything that writes to Health Connect) for a few days. +PulseLoop reads that device's records back out of Health Connect, lines them up against its own, +and reports where the ring agrees, where it falls short, and by how much. Where the gap is a +**consistent bias** rather than noise, the user can turn on a correction. + +While the check runs, PulseLoop **stops writing to Health Connect**, so the two devices don't +double-count the same steps, sleep and heart rate in every other app reading Health Connect. + +### Naming: not "Diagnose" + +Settings already has a *Diagnostics* area: the debug console, `DiagnosticsExporter`, raw packet +capture. A second "Diagnose" entry next to it would be mistaken for it, and bug reports would +mix the two up. Working name: **Settings → Accuracy check** (subtitle "Compare your ring with +another device"). The code name in this doc is `AccuracyCheck`. + +## What already exists and gets reused + +| Need | Existing piece | Note | +| --- | --- | --- | +| Health Connect client, availability | `HealthConnectSdk`, `HealthConnectAvailability` | as-is | +| A *read* path with its own opt-in and permissions | `HealthConnectBodyImport` | the model for this feature: separate permission set, separate prefs, never mixed with the export's `HealthConnectPermissions.all` | +| Pausing the export | `HealthConnectExportWorker.doWork` already returns early on `!prefs.enabled` / `NOT_ASKED` | add one more gate | +| Skip a window on resume | watermarks + `effectiveWatermark(stored, newOnlyConsentAt)` | the "export new only" mechanism already does exactly this | +| Ring data | `measurements`, `activity_daily`, `activity_buckets`, `sleep_sessions` + `sleep_stage_blocks` | read through the `*Real` DAO queries, never demo rows (`DemoDataPolicy`) | +| Sleep definitions | `asleepMinutes(blocks)`, `TimeUtil.wakingDayLocal` | compare on the same definition the app displays | +| Process-wide services | `AppServices` | the session controller lives here, not in a composable (issue #113) | + +## User flow + +1. **Settings → Accuracy check → Start.** Explainer: wear both devices for N days, ring on a + finger, the other device on the wrist as usual. Health Connect export pauses while it runs. +2. **Read permission sheet** for the comparison types only (steps, heart rate, sleep, resting + HR, SpO₂, HRV, distance, calories). Partial grants are fine: a type the user denies is left + out of the report. +3. **Pick the reference source.** PulseLoop lists the apps that wrote to Health Connect over the + last 7 days (`DataOrigin` package names, mapped to app labels) and which types each one wrote, + e.g. *Fitbit: steps, heart rate, sleep. Samsung Health: steps.* PulseLoop's own package is + never offered. The user picks one source. Types that source never writes are shown greyed + out with "Fitbit doesn't share this with Health Connect", so nobody waits a week for a + comparison that can't happen. +4. **Duration**: 3, 5, 7 (default) or 14 days. At least 3 nights, because one night of sleep + data says almost nothing. +5. **While running**: a small banner in Settings and Today, "Accuracy check · day 3 of 7 · + Health Connect export paused". There's a live "so far" view, labelled preliminary until + enough data has been paired. +6. **End**, automatically after N days or early by hand → the **report** → the + **resume-export choice** (below) → optional **corrections**. + +## Export pause and resume + +- New pref `accuracyCheck.activeSince: Long?`. `HealthConnectExportWorker.doWork` returns + `Result.success()` with a log line while it is set. The gate goes in the worker, not at the 8 + `enqueue` call sites, so no trigger can slip past it. +- The export settings screen shows "Paused by Accuracy check (ends Oct 28)", and the user can't + turn export back on there while the check runs. They end the check instead, so there is one + switch and not two that disagree. +- **On resume, the default is to skip the check window.** If the watermarks were simply left + alone, the first pass after the check would export the whole window, and the duplicates the + pause existed to prevent would land in Health Connect anyway, just a week late. The resume + dialog offers: + - **Skip these days (recommended)**: move each `HealthConnectWatermarks.Key` to the check's + end, the same way `EXPORT_NEW_ONLY` already works. + - **Export them too**: leave the watermarks alone, for a user who will take the reference + device off afterwards and wants a complete ring history in Health Connect. +- Records PulseLoop exported *before* the check stay in Health Connect. The comparison filters + them out by `DataOrigin` (below), so they don't get in the way. +- Process death, reboot or an app update mid-check: everything is persisted, and the check + picks up where it left off. A WorkManager job ends the check at `activeSince + N days` even if + the app is never opened. It posts a "Your accuracy report is ready" notification and leaves + export **paused until the user answers the resume dialog**. Resuming silently would make the + choice for them. + +## Reading the reference data + +- Every read is filtered with `dataOriginFilter = setOf(DataOrigin(referencePackage))`. This is + the most important correctness rule in the feature. Without it, PulseLoop's own records from + before the check, or a third app re-syncing the same data, end up compared against themselves + and the report reads "perfect agreement". +- Prefer the `aggregate` / `aggregateGroupByDuration` APIs for steps, distance and calories. + They return the reference's per-hour totals without paging through raw records, and they + respect the origin filter. +- Reading history: Health Connect only lets an app read 30 days before its first grant unless + it holds `READ_HEALTH_DATA_HISTORY`. The check window lies after the grant, so this doesn't + apply. Don't ask for that permission. +- Background reads have tighter rate limits than foreground ones. Do the heavy read when the + report is opened (foreground), plus at most one small incremental read per day for the live + view. +- **No raw reference samples are stored.** For each day and metric, the engine reduces the + reference data to the figures the report needs (totals, paired-error statistics). Only those + are persisted, in `accuracy_check_days`. Another device's raw health data has no business in + PulseLoop's archive, and it would be the first foreign health data the app keeps. + Trade-off: if the reference app later revises a day, the stored result doesn't follow. That's + acceptable, and "Recompute" on the report re-reads while the data is still in Health Connect. + +## Comparison engine + +A pure Kotlin module (`AccuracyComparison`) with no Health Connect or Room imports. It takes two +plain time series and returns statistics, so it can be unit-tested the way +`HealthConnectTypeMappings` is. + +### Two ideas behind every metric + +1. **Agreement band ("buffer")**: how close is close enough. Each metric has a default, and the + user can change it. A day or a pair inside the band counts as agreeing. +2. **Bias vs noise.** For every metric, report the **mean difference (bias)** and the **spread + of the differences (limits of agreement, ±1.96 SD, Bland-Altman)** separately. They lead to + different advice: + - large bias, small spread → the ring is consistently off, and a correction *will* help; + - small bias, large spread → the ring is erratic, and no correction can fix that. Say so + plainly instead of offering a slider that only moves the average. + +### Per metric + +| Metric | Pairing | Headline figures | Default band | +| --- | --- | --- | --- | +| **Steps** | hourly buckets (`activity_buckets` vs reference `StepsRecord` aggregated per hour) + daily totals | daily % difference, bias, hours where the ring missed activity entirely | ±10 % per day | +| **Distance** | daily totals | % difference | ±15 % | +| **Sleep: duration** | per waking day (`wakingDayLocal`) | asleep minutes (ring's `asleepMinutes` vs reference stages except AWAKE / `SLEEPING`), bias | ±30 min | +| **Sleep: timing** | per night | onset and final-wake difference | ±20 min | +| **Sleep: stages** | minute by minute over the overlap, only if the reference reports stages | % of minutes on the same stage, a deep/light/REM/awake confusion table | report only | +| **Heart rate** | each ring sample against the reference's nearest sample within ±60 s | mean absolute error, bias, limits of agreement, split **at rest** (asleep, or <50 steps in that hour) vs **active** | ±5 bpm | +| **Resting HR** | daily `RestingHeartRateRecord` vs the app's own resting HR | daily difference | ±3 bpm | +| **SpO₂** | nearest sample within ±5 min, mostly overnight | bias, % of pairs in band | ±2 points | +| **HRV (RMSSD)** | nightly value only | bias, and whether the two move up and down together (rank correlation) | report only | +| **Calories** | daily | % difference | report only | + +Notes on the choices above: + +- **HR is split by context** because the cheap-ring complaint is mostly about exercise: optical + sensors on a finger lose the signal when the hand moves. One blended figure would hide a ring + that is excellent at rest and poor during a run, which is the most useful thing the report + can tell the user. +- **HRV and calories are report-only.** Vendors compute HRV in different ways (different + windows, different times of night). Calories are an estimate on both sides, and the ring's + figure may be the app's own `DailyCalorieEstimator` estimate. So a difference here doesn't + show which device is wrong, and a correction would only paper over it. +- **Temperature is left out.** Fitbit and most watches publish skin-temperature *variation*, + not an absolute value, so there's nothing to pair against. +- **A minimum sample size per metric** (e.g. 3 nights, 500 HR pairs, 3 full days of steps). + Below it the metric shows "Not enough data yet" instead of a number. Same rule as + `DerivedStress` returning null below twelve readings: a number the data doesn't support, + shown on a health screen, gets read as a measurement. +- **Days where either device was clearly not worn don't count.** For example, a reference day + with < 500 steps or under 12 hours of HR coverage, or a ring day with a long data gap. A day + the watch spent charging is not a day the ring overcounted. + +### The reference is not ground truth + +Fitbit and the other watches are consumer devices too. The report should say "differs from +Fitbit by" and not "is wrong by", and the explainer should say once, briefly, that this is +agreement with the device the user chose, not a lab measurement. The corrections below assume +the reference is the better device because that is what the user told us. The app shouldn't +claim it for them. + +## The report + +- One card per metric. Each card has a verdict chip (**Agrees** / **Consistently high/low** / + **Inconsistent** / **Not enough data**), the headline number, and a one-line plain-language + reading. Example: *"Your ring counts about 18 % fewer steps than Fitbit, consistently, every + day. A correction would help."* +- Tapping a card opens detail: a day-by-day bar chart of ring vs reference, a Bland-Altman + scatter for HR and SpO₂, and the stage confusion table for sleep. +- The summary at the top lists the metrics outside their band, worst first. This is the "point + where the ring is falling short" part of the request. +- Bands are editable from the report, and the verdicts recompute at once. This needs no new + read, since the stored per-day statistics are enough. + +## Corrections ("make the ring more accurate") + +This part needs the most care, because several hard-won rules in `AGENTS.md` bear on it: +*"disagreeing with the ring is not a better number"* (issue #59/#60), *"a derived metric must +say it is derived"* (#67), and the ring re-supplying its own history on every sync. + +**Rules:** + +1. **Stored data is never rewritten.** Rows in `measurements`, `activity_*` and `sleep_*` stay + exactly as the ring sent them. The ring re-sends history on every sync and `upsert` would + overwrite a corrected row anyway. A correction is a **read-time transform** applied where + values are shown, in one place (`AccuracyCorrections.apply(kind, value, context)`), so it can + be switched off and everything goes back to raw. +2. **Only offered where the report found a consistent bias.** The "Inconsistent" verdict gets no + correction button, just the explanation. This stops the feature from implying it can repair + a ring that is simply noisy. +3. **Simple, explainable forms only:** + - steps and distance: a **scale factor** (e.g. ×1.18), fitted as total reference ÷ total ring + over the valid days; + - heart rate: a **bpm offset**, kept separately for *rest* and *active*, since the two biases + often differ; + - sleep: an **onset/wake time offset** and a **duration offset**. Sleep *stages* are never + corrected; the report only describes the confusion. + - SpO₂ and resting HR: an offset. + The fitted value is a suggestion. The user can accept it, adjust it with a slider, or decline. +4. **Labelled wherever it's shown.** A corrected figure carries a small "adjusted" marker, the + same way `VitalsState.stressIsDerived` drives the derived-stress caption. Detail screens say + "Adjusted from ring reading 7,412 (×1.18, from your Oct 21–28 accuracy check)". +5. **What a correction does *not* touch:** + - Health Connect export sends **raw** values by default. A corrected value in Health Connect + would be indistinguishable from a measured one, for every app reading it. That's an open + question below, not a default. + - Values that are persisted or derived (`hrRestingBaseline`, HR zones, + `estimatedActiveCalories`) keep using raw values in the first version. Feeding corrected + values into persisted figures makes a correction hard to undo, the same trap + `DemoDataPolicy` describes for demo data. +6. **Corrections belong to one ring.** Key them by device identity (address + model). Pairing a + different ring turns them off and prompts "Run an accuracy check for this ring?". A + correction fitted for an R11 applied to an R10 would be invented data. +7. **Corrections go stale.** Show "fitted 3 months ago, re-check?" after ~90 days or after a + firmware change (the firmware revision is already decoded on several families). + +## Data model (Room, v36) + +- `accuracy_checks`: id, deviceKey, referencePackage, referenceLabel, startedAt, plannedEndAt, + endedAt, state (RUNNING / AWAITING_RESUME_CHOICE / DONE / CANCELLED), bandsJson. +- `accuracy_check_days`: checkId, metric, dayEpoch, ringValue, refValue, pairCount, meanDiff, + sdDiff, mae, validDay flag. These are aggregates only; no raw samples (see above). +- `accuracy_corrections`: deviceKey, metric, context (rest/active/—), kind (SCALE/OFFSET), value, + fittedValue, fromCheckId, enabled, createdAt. +- Archive: all three go in `PulseArchive` (they are the user's own findings). Diagnostics export: + **none of them**, per the "export carries no database rows" rule. If a shareable summary is + ever wanted (below), it is a separate, explicit "Share report" action. + +## Phases + +0. **Foundation**: a read-permission set (`AccuracyCheckPermissions`, separate from export and + body import), manifest entries, the reference-source discovery screen. Value on its own: the + user can see what each app actually shares with Health Connect. *Verify on real devices + which types Fitbit and Samsung Health actually write; this decides what the report can + cover.* +1. **Session lifecycle + export pause**: prefs/table, worker gate, export-screen state, end job, + notification, resume dialog with watermark skip. Unit-test the watermark move. +2. **Engine + report for steps, sleep, HR**: the pure comparison module with tests built from + synthetic series (constant bias, pure noise, missing hours, a non-wear day, a nap, a night + that crosses 20:00/midnight), and the report UI. +3. **Remaining metrics**: resting HR, SpO₂, distance, HRV, calories. +4. **Corrections**: read-time transform, labelling everywhere a corrected value is shown, + keyed to the ring, stale prompt. +5. *(Optional)* **Shareable summary**: a text/image of the verdicts and headline numbers, with + model and firmware, no raw values. Useful in GitHub issues ("my SR08 undercounts steps by + 20 %") and, over time, as crowd-sourced accuracy notes per model. + +## Open questions + +1. **Should corrected values ever go to Health Connect?** Proposed: no in v1. Possibly a later + opt-in with the correction recorded in the record's metadata. +2. **Should corrections feed HR zones / resting baseline / calorie estimates?** Proposed: not in + v1 (see rule 5). +3. **Pause the export per type instead of all of it?** If the reference device only writes steps + and sleep, PulseLoop's SpO₂/HRV would duplicate nothing and could keep exporting. More + correct, a little more UI. Proposed: pause only the types the chosen reference actually + writes, and say which ones on the banner. +4. **iOS**: the same feature maps onto HealthKit (`HKSource` plays the part of `DataOrigin`). + Worth tracking as an iOS-parity item once the Android version has proved itself. From 1789d99dc9f6e81f39eda4a05c3c63eecfa1b641 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 14:51:05 +0000 Subject: [PATCH 2/9] =?UTF-8?q?docs:=20accuracy=20check=20=E2=80=94=20reco?= =?UTF-8?q?rd=20decisions,=20per-type=20pause,=20Health=20Sync,=20ring=20c?= =?UTF-8?q?hanges?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/accuracy-check-plan.md | 158 ++++++++++++++++++++++++++++-------- 1 file changed, 126 insertions(+), 32 deletions(-) diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md index f5ef081d..3c1efaf4 100644 --- a/docs/accuracy-check-plan.md +++ b/docs/accuracy-check-plan.md @@ -56,18 +56,33 @@ another device"). The code name in this doc is `AccuracyCheck`. ## Export pause and resume -- New pref `accuracyCheck.activeSince: Long?`. `HealthConnectExportWorker.doWork` returns - `Result.success()` with a log line while it is set. The gate goes in the worker, not at the 8 - `enqueue` call sites, so no trigger can slip past it. -- The export settings screen shows "Paused by Accuracy check (ends Oct 28)", and the user can't - turn export back on there while the check runs. They end the check instead, so there is one +- **Only the types the reference writes are paused** (decided). The pause set is a list of export + rows (`HealthConnectPermissions.DataTypeRow`), not one switch. With a Health Sync/Huawei + reference that writes steps, sleep and HR, PulseLoop keeps exporting SpO₂, HRV, temperature + and the rest, because those would duplicate nothing. The gate lives in + `HealthConnectExporter.run`, next to the existing per-kind permission check: a row in the pause + set is skipped **and its watermark isn't advanced**, so the resume choice below still applies to + it. `HealthConnectExportWorker` itself keeps running. +- **The pause set comes from the reference device, never from the ring.** It's what the + reference was seen writing in Health Connect, re-read once a day during the check. It does + **not** come from the current ring's capability list. That way a ring change can't create a + duplicate: if the user switches to a ring that measures SpO₂ and the reference writes SpO₂ too, + SpO₂ was paused already. A type the reference *starts* writing mid-check (the user switches + on a new sync category in Health Sync) joins the pause set from that day on, and its watermark + is held from that day. +- The export settings screen marks each paused row "Paused by Accuracy check (ends Oct 28)", and + the user can't switch those rows back on while the check runs. They end the check instead, so there is one switch and not two that disagree. - **On resume, the default is to skip the check window.** If the watermarks were simply left alone, the first pass after the check would export the whole window, and the duplicates the pause existed to prevent would land in Health Connect anyway, just a week late. The resume dialog offers: - - **Skip these days (recommended)**: move each `HealthConnectWatermarks.Key` to the check's - end, the same way `EXPORT_NEW_ONLY` already works. + - **Skip these days (recommended)**: move the watermark of every *paused* group to the check's + end, the same way `EXPORT_NEW_ONLY` already works. Groups that weren't paused have exported + all along and are left alone. Watermarks are per group (`VITALS` covers HR, SpO₂, HRV…), so + the skip has to be per kind within `VITALS`, not per watermark key, or skipping HR would also + skip the SpO₂ that never paused. That makes it a small exporter change, not just a prefs + write, and it needs its own test. - **Export them too**: leave the watermarks alone, for a user who will take the reference device off afterwards and wants a complete ring history in Health Connect. - Records PulseLoop exported *before* the check stay in Health Connect. The comparison filters @@ -78,6 +93,58 @@ another device"). The code name in this doc is `AccuracyCheck`. export **paused until the user answers the resume dialog**. Resuming silently would make the choice for them. +## Reference via Health Sync (the Huawei case) + +The first real user's reference is a Huawei device whose data reaches Health Connect through +**Health Sync** (a third-party bridge app), not from Huawei directly. What that changes: + +- **The `DataOrigin` is Health Sync's package, not Huawei's.** Discovery lists "Health Sync", and + filtering on it is correct. Health Connect has no record of the original source, so the screen + should show the label as "Health Sync" and offer to name it ("Health Sync (Huawei Watch GT 4)"). + If `Metadata.device` (manufacturer/model) is filled in on Health Sync's records, show that + instead. *Unverified whether Health Sync fills it in; check in Phase 0.* +- **A bridge can relay more than one source.** Health Sync may be copying from Huawei Health + *and* from somewhere else (Google Fit, Samsung Health). The origin filter can't separate those. + If `Metadata.device` is present and varies, offer a device filter on top of the origin filter. + If not, the explainer says to set Health Sync to sync from the watch only during the check. +- **Echo risk: the ring's own data coming back as the "reference".** Health Sync can also *read* + Health Connect and write elsewhere. If it is set up two-way (Health Connect → Huawei Health → + Health Connect), PulseLoop's earlier exports could come back under Health Sync's origin, and the + report would say the ring agrees perfectly with itself. The origin filter doesn't catch this. + Guard: an **echo check** in the engine. If a large share of reference samples match ring + samples exactly (same value, timestamp within a second), stop and show "The reference data + looks like PulseLoop's own — check Health Sync's sync direction". The per-type pause also + helps from the start of the check on, but it does nothing about history that echoed earlier. +- **Lag.** Health Sync syncs on its own schedule (periodically, not live), and Huawei Health syncs + from the watch on its own schedule before that. So the most recent day is usually incomplete. + The engine only scores a day once reference data covers it to the end, or 24 h have passed. + When the check ends, the report waits for the last day ("Waiting for Health Sync to deliver + Oct 28 — open Health Sync to sync now") before scoring it. Without this, the last day would + always read as "ring overcounts". +- **Granularity.** Whatever Huawei exports is what we get. HR may arrive as sparser samples than + the ring's, and sleep stages may be mapped by Health Sync to Health Connect's stage set. The + pairing windows above (±60 s HR, ±5 min SpO₂) may need widening per source. Phase 0 measures + the actual cadence on this setup before the engine fixes those numbers. + +## Changing rings + +A user can swap rings, mid-check or between checks, and the new ring may measure things the old +one didn't. The rules: + +- **A check belongs to one ring** (`deviceKey`). If a different ring connects mid-check, the check + for the old ring **ends early**: its days so far are kept and reported as a partial check for + that ring. The user is offered a new check for the new ring. Data from two rings is never + scored as one ring's. The export pause stays in place across the switch (it follows the + reference, see above) until the user answers the resume dialog or starts the new check. +- **What gets compared = what both devices produce.** This is decided at scoring time, not when + the check starts. A new ring with HRV, SpO₂ or temperature gets those metrics in its report + as long as the reference writes them. A metric the new ring has and the reference doesn't + shows "Your reference device doesn't share this", which is a different case from "not enough + data". +- **Corrections are per ring.** A new ring starts with none, and the old ring's are kept, so + they come back if that ring is paired again. The new ring's Settings entry says "No accuracy + check for this ring yet". + ## Reading the reference data - Every read is filtered with `dataOriginFilter = setOf(DataOrigin(referencePackage))`. This is @@ -201,18 +268,31 @@ say it is derived"* (#67), and the ring re-supplying its own history on every sy 4. **Labelled wherever it's shown.** A corrected figure carries a small "adjusted" marker, the same way `VitalsState.stressIsDerived` drives the derived-stress caption. Detail screens say "Adjusted from ring reading 7,412 (×1.18, from your Oct 21–28 accuracy check)". -5. **What a correction does *not* touch:** - - Health Connect export sends **raw** values by default. A corrected value in Health Connect - would be indistinguishable from a measured one, for every app reading it. That's an open - question below, not a default. - - Values that are persisted or derived (`hrRestingBaseline`, HR zones, - `estimatedActiveCalories`) keep using raw values in the first version. Feeding corrected - values into persisted figures makes a correction hard to undo, the same trap - `DemoDataPolicy` describes for demo data. -6. **Corrections belong to one ring.** Key them by device identity (address + model). Pairing a - different ring turns them off and prompts "Run an accuracy check for this ring?". A +5. **Corrections never reach Health Connect** (decided). The export always sends raw ring values. + A corrected value in Health Connect would look like a measurement to every app reading it. +6. **Corrections do feed the app's own derived figures** (decided): resting-HR baseline, HR zones, + calorie estimates. These two decisions meet at two values that are *both* derived *and* + exported, so each of those needs a raw copy and an adjusted copy: + - **Resting-HR baseline.** `RestingHRBaselineService` keeps computing `hrRestingBaseline` from + raw HR; that's the value `RestingHeartRateExporter` sends. The adjusted baseline isn't + stored. The baseline is a percentile (p10) and the HR correction at rest is an offset, and + an offset shifts a percentile by exactly itself, so adjusted = raw + rest offset, computed + at read time. `HeartRateZones` / `VitalsZoneModel` read the adjusted value. + - **Estimated active calories.** `DailyCalorieEstimator.estimateNetActive` isn't linear in its + inputs (HR thresholds, step buckets), so there's no shortcut. Add a second column, + `activity_daily.estimatedActiveCaloriesAdjusted`. The estimator writes both from the same + buckets (raw inputs and corrected inputs); the activity exporter keeps reading the raw + column and the UI reads the adjusted one. + - **Undo must be exact.** Switching a correction off, changing its value, or a ring change that + turns corrections off: each one re-runs the estimator over the days the correction covered + and recomputes the zones. The figures go back to exactly what they were. Since only the + adjusted copies are ever touched, the raw ones are always there to recompute from. + - The device-reported calories path (`deviceReportedCalories`) is left alone. A correction + derived from steps doesn't apply to a figure the ring computed with its own formula. +7. **Corrections belong to one ring.** Key them by device identity (address + model). Pairing a + different ring turns them off (see "Changing rings") and prompts "Run an accuracy check for this ring?". A correction fitted for an R11 applied to an R10 would be invented data. -7. **Corrections go stale.** Show "fitted 3 months ago, re-check?" after ~90 days or after a +8. **Corrections go stale.** Show "fitted 3 months ago, re-check?" after ~90 days or after a firmware change (the firmware revision is already decoded on several families). ## Data model (Room, v36) @@ -221,6 +301,9 @@ say it is derived"* (#67), and the ring re-supplying its own history on every sy endedAt, state (RUNNING / AWAITING_RESUME_CHOICE / DONE / CANCELLED), bandsJson. - `accuracy_check_days`: checkId, metric, dayEpoch, ringValue, refValue, pairCount, meanDiff, sdDiff, mae, validDay flag. These are aggregates only; no raw samples (see above). +- `accuracy_check_paused_rows`: checkId, row, pausedFrom (the day the reference was first seen + writing it, which is what the skip-on-resume moves the watermark past). +- `activity_daily.estimatedActiveCaloriesAdjusted: Double?` (null = no correction applied). - `accuracy_corrections`: deviceKey, metric, context (rest/active/—), kind (SCALE/OFFSET), value, fittedValue, fromCheckId, enabled, createdAt. - Archive: all three go in `PulseArchive` (they are the user's own findings). Diagnostics export: @@ -230,31 +313,42 @@ say it is derived"* (#67), and the ring re-supplying its own history on every sy ## Phases 0. **Foundation**: a read-permission set (`AccuracyCheckPermissions`, separate from export and - body import), manifest entries, the reference-source discovery screen. Value on its own: the + body import), manifest entries, the reference-source discovery screen (with per-type sample + cadence and `Metadata.device`, if any, so the Health Sync questions get answered here). Value on its own: the user can see what each app actually shares with Health Connect. *Verify on real devices which types Fitbit and Samsung Health actually write; this decides what the report can cover.* -1. **Session lifecycle + export pause**: prefs/table, worker gate, export-screen state, end job, - notification, resume dialog with watermark skip. Unit-test the watermark move. +1. **Session lifecycle + per-type export pause**: table, the exporter's per-row pause gate that + holds watermarks, daily refresh of the pause set, export-screen state, end job, notification, + resume dialog with the per-kind skip, early end on a ring change. Unit-test the skip and that + an unpaused kind inside `VITALS` keeps exporting. 2. **Engine + report for steps, sleep, HR**: the pure comparison module with tests built from synthetic series (constant bias, pure noise, missing hours, a non-wear day, a nap, a night - that crosses 20:00/midnight), and the report UI. + that crosses 20:00/midnight, an echoed series, a last day the reference hasn't delivered + yet), and the report UI. 3. **Remaining metrics**: resting HR, SpO₂, distance, HRV, calories. 4. **Corrections**: read-time transform, labelling everywhere a corrected value is shown, - keyed to the ring, stale prompt. + keyed to the ring, stale prompt; the adjusted baseline, zones and + `estimatedActiveCaloriesAdjusted` column (v37 or folded into v36), with recompute on every + correction change. Test that switching a correction off restores every derived figure exactly + and that the export payload is the same with corrections on and off. 5. *(Optional)* **Shareable summary**: a text/image of the verdicts and headline numbers, with model and firmware, no raw values. Useful in GitHub issues ("my SR08 undercounts steps by 20 %") and, over time, as crowd-sourced accuracy notes per model. +## Decisions (2026-10-21) + +1. **Corrected values never go to Health Connect.** Export is raw, always (Corrections rule 5). +2. **Corrections feed resting-HR baseline, HR zones and calorie estimates**, with raw and + adjusted copies kept apart where a figure is also exported (rule 6). +3. **The pause covers only the types the reference device writes**, decided from the reference + and not the ring, so a ring change can't open a duplication gap (Export pause; Changing + rings). + ## Open questions -1. **Should corrected values ever go to Health Connect?** Proposed: no in v1. Possibly a later - opt-in with the correction recorded in the record's metadata. -2. **Should corrections feed HR zones / resting baseline / calorie estimates?** Proposed: not in - v1 (see rule 5). -3. **Pause the export per type instead of all of it?** If the reference device only writes steps - and sleep, PulseLoop's SpO₂/HRV would duplicate nothing and could keep exporting. More - correct, a little more UI. Proposed: pause only the types the chosen reference actually - writes, and say which ones on the banner. -4. **iOS**: the same feature maps onto HealthKit (`HKSource` plays the part of `DataOrigin`). +1. **iOS**: the same feature maps onto HealthKit (`HKSource` plays the part of `DataOrigin`). Worth tracking as an iOS-parity item once the Android version has proved itself. +2. **Health Sync specifics** to confirm on the real Huawei setup in Phase 0: whether + `Metadata.device` is filled in, HR sample cadence, how sleep stages are mapped, and typical + sync lag. From a8479e4f5adde9ea65db823a7622a03d0fc9f055 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 14:51:12 +0000 Subject: [PATCH 3/9] =?UTF-8?q?docs:=20accuracy=20check=20=E2=80=94=20fix?= =?UTF-8?q?=20stale=20field=20name?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/accuracy-check-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md index 3c1efaf4..a5c1b746 100644 --- a/docs/accuracy-check-plan.md +++ b/docs/accuracy-check-plan.md @@ -88,7 +88,7 @@ another device"). The code name in this doc is `AccuracyCheck`. - Records PulseLoop exported *before* the check stay in Health Connect. The comparison filters them out by `DataOrigin` (below), so they don't get in the way. - Process death, reboot or an app update mid-check: everything is persisted, and the check - picks up where it left off. A WorkManager job ends the check at `activeSince + N days` even if + picks up where it left off. A WorkManager job ends the check at `startedAt + N days` even if the app is never opened. It posts a "Your accuracy report is ready" notification and leaves export **paused until the user answers the resume dialog**. Resuming silently would make the choice for them. From ad21dfda2509c04283a922e3368c5afbf3309c16 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 14:59:28 +0000 Subject: [PATCH 4/9] Accuracy check Phase 0: survey which apps write what to Health Connect MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- app/src/main/AndroidManifest.xml | 16 +- .../health/HealthConnectRationaleActivity.kt | 3 +- .../accuracy/AccuracyCheckPermissions.kt | 47 ++++ .../health/accuracy/ReferenceSourceScanner.kt | 143 ++++++++++++ .../health/accuracy/ReferenceSurvey.kt | 171 +++++++++++++++ .../health/accuracy/ReferenceSurveyText.kt | 135 ++++++++++++ .../java/com/pulseloop/ui/PulseLoopApp.kt | 3 + .../pulseloop/ui/screens/AccuracyCheckUi.kt | 203 ++++++++++++++++++ .../pulseloop/ui/screens/SettingsScreen.kt | 3 + .../ui/screens/SettingsSubScreens.kt | 2 +- .../health/accuracy/ReferenceSurveyTest.kt | 136 ++++++++++++ docs/accuracy-check-plan.md | 10 +- 12 files changed, 867 insertions(+), 5 deletions(-) create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckPermissions.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/ReferenceSourceScanner.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurvey.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurveyText.kt create mode 100644 app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt create mode 100644 app/src/test/java/com/pulseloop/health/accuracy/ReferenceSurveyTest.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index f9558d2f..f00ad259 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -46,7 +46,8 @@ + first permission sheet stayed narrow. The export itself holds no READ_* permissions; the + two read paths below each ask for their own. --> @@ -66,7 +67,7 @@ - + @@ -74,6 +75,17 @@ + + + + + + + + + ) { + STEPS("Steps", StepsRecord::class), + DISTANCE("Distance", DistanceRecord::class), + ACTIVE_CALORIES("Active calories", ActiveCaloriesBurnedRecord::class), + HEART_RATE("Heart rate", HeartRateRecord::class), + RESTING_HEART_RATE("Resting heart rate", RestingHeartRateRecord::class), + SLEEP("Sleep", SleepSessionRecord::class), + OXYGEN_SATURATION("Blood oxygen", OxygenSaturationRecord::class), + HRV("HRV", HeartRateVariabilityRmssdRecord::class), +} + +/** + * The accuracy check's Health Connect **read** permissions — a third set, kept apart from the + * export's write set ([com.pulseloop.health.HealthConnectPermissions.all]) and the scale import's + * reads ([com.pulseloop.health.HealthConnectBodyImport.permissions]). The export's reconcile + * filters the granted set down to its own permissions, so granting these never looks like an + * export grant or revoke. Derived from the record classes, never hardcoded; also declared in the + * manifest. + */ +object AccuracyCheckPermissions { + + fun readPermission(metric: ReferenceMetric): String = HealthPermission.getReadPermission(metric.recordType) + + val all: Set = ReferenceMetric.entries.map(::readPermission).toSet() + + /** The metrics [granted] lets the scan read. */ + fun readable(granted: Set): Set = + ReferenceMetric.entries.filter { readPermission(it) in granted }.toSet() +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSourceScanner.kt b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSourceScanner.kt new file mode 100644 index 00000000..be661acd --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSourceScanner.kt @@ -0,0 +1,143 @@ +package com.pulseloop.health.accuracy + +import android.content.Context +import android.util.Log +import androidx.health.connect.client.HealthConnectClient +import androidx.health.connect.client.records.ActiveCaloriesBurnedRecord +import androidx.health.connect.client.records.DistanceRecord +import androidx.health.connect.client.records.HeartRateRecord +import androidx.health.connect.client.records.HeartRateVariabilityRmssdRecord +import androidx.health.connect.client.records.OxygenSaturationRecord +import androidx.health.connect.client.records.Record +import androidx.health.connect.client.records.RestingHeartRateRecord +import androidx.health.connect.client.records.SleepSessionRecord +import androidx.health.connect.client.records.StepsRecord +import androidx.health.connect.client.records.metadata.Metadata +import androidx.health.connect.client.request.ReadRecordsRequest +import androidx.health.connect.client.time.TimeRangeFilter +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.health.HealthConnectAvailability +import com.pulseloop.health.HealthConnectSdk +import com.pulseloop.ring.MeasurementKind +import java.time.Instant +import kotlin.reflect.KClass + +/** + * Reads the last week of Health Connect for every type the accuracy check could compare and hands + * it to [ReferenceSurveyBuilder] (docs/accuracy-check-plan.md, Phase 0). Foreground only — it runs + * when the user taps Scan — because background reads get a much smaller rate-limit quota. + */ +object ReferenceSourceScanner { + + private const val TAG = "AccuracyScan" + const val LOOKBACK_DAYS = 7L + /** Pages per type (1 000 records each). A week of anything fits well inside this; the cap is + * only there so a source writing absurd volumes can't keep the screen spinning. */ + private const val MAX_PAGES = 20 + + sealed interface Result { + data object Unavailable : Result + data class Done( + val sources: List, + val readable: Set, + val failed: Set, + val scannedAt: Long, + ) : Result { + val unreadable: Set get() = ReferenceMetric.entries.toSet() - readable + } + } + + suspend fun grantedPermissions(context: Context): Set { + if (HealthConnectSdk.availability(context) != HealthConnectAvailability.AVAILABLE) return emptySet() + return runCatching { + HealthConnectClient.getOrCreate(context).permissionController.getGrantedPermissions() + }.getOrDefault(emptySet()) + } + + suspend fun scan(context: Context, now: Long = System.currentTimeMillis()): Result { + if (HealthConnectSdk.availability(context) != HealthConnectAvailability.AVAILABLE) return Result.Unavailable + val client = HealthConnectClient.getOrCreate(context) + val readable = AccuracyCheckPermissions.readable(grantedPermissions(context)) + val since = now - LOOKBACK_DAYS * 86_400_000L + val range = TimeRangeFilter.between(Instant.ofEpochMilli(since), Instant.ofEpochMilli(now)) + val builder = ReferenceSurveyBuilder(ownPackage = context.packageName) + val failed = mutableSetOf() + + for (metric in readable) { + runCatching { + when (metric) { + ReferenceMetric.STEPS -> readAll(client, StepsRecord::class, range) { + builder.add(interval(metric, it.metadata, it.startTime, it.endTime)) + } + ReferenceMetric.DISTANCE -> readAll(client, DistanceRecord::class, range) { + builder.add(interval(metric, it.metadata, it.startTime, it.endTime)) + } + ReferenceMetric.ACTIVE_CALORIES -> readAll(client, ActiveCaloriesBurnedRecord::class, range) { + builder.add(interval(metric, it.metadata, it.startTime, it.endTime)) + } + ReferenceMetric.HEART_RATE -> readAll(client, HeartRateRecord::class, range) { r -> + builder.add( + record(metric, r.metadata, r.samples.map { it.time.toEpochMilli() }, r.endTime).copy( + heartRate = r.samples.map { TimedValue(it.time.toEpochMilli(), it.beatsPerMinute.toDouble()) }, + ), + ) + } + ReferenceMetric.RESTING_HEART_RATE -> readAll(client, RestingHeartRateRecord::class, range) { + builder.add(record(metric, it.metadata, listOf(it.time.toEpochMilli()), it.time)) + } + ReferenceMetric.SLEEP -> readAll(client, SleepSessionRecord::class, range) { r -> + builder.add( + interval(metric, r.metadata, r.startTime, r.endTime) + .copy(sleepStageTypes = r.stages.map { it.stage }.toSet()), + ) + } + ReferenceMetric.OXYGEN_SATURATION -> readAll(client, OxygenSaturationRecord::class, range) { + builder.add(record(metric, it.metadata, listOf(it.time.toEpochMilli()), it.time)) + } + ReferenceMetric.HRV -> readAll(client, HeartRateVariabilityRmssdRecord::class, range) { + builder.add(record(metric, it.metadata, listOf(it.time.toEpochMilli()), it.time)) + } + } + }.onFailure { + Log.w(TAG, "read ${metric.name} failed", it) + failed += metric + } + } + + val ringHr = runCatching { + PulseLoopDatabase.getInstance(context).measurementDao() + .rangeReal(MeasurementKind.HEART_RATE.name, since, now) + .map { TimedValue(it.timestamp, it.value) } + }.getOrDefault(emptyList()) + + return Result.Done(builder.build(ringHr), readable, failed, now) + } + + private fun interval(metric: ReferenceMetric, meta: Metadata, start: Instant, end: Instant) = + record(metric, meta, listOf(start.toEpochMilli()), end) + + private fun record(metric: ReferenceMetric, meta: Metadata, times: List, end: Instant) = SurveyRecord( + packageName = meta.dataOrigin.packageName, + metric = metric, + sampleTimes = times, + endTime = end.toEpochMilli(), + lastModified = meta.lastModifiedTime.toEpochMilli(), + device = meta.device?.let { DeviceInfo(it.manufacturer, it.model, it.type) }, + ) + + private suspend fun readAll( + client: HealthConnectClient, + type: KClass, + range: TimeRangeFilter, + consume: (T) -> Unit, + ) { + var token: String? = null + var pages = 0 + do { + val response = client.readRecords(ReadRecordsRequest(type, range, pageSize = 1000, pageToken = token)) + response.records.forEach(consume) + token = response.pageToken + pages++ + } while (token != null && pages < MAX_PAGES) + } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurvey.kt b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurvey.kt new file mode 100644 index 00000000..6b4bcf08 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurvey.kt @@ -0,0 +1,171 @@ +package com.pulseloop.health.accuracy + +import kotlin.math.abs + +/** + * Phase 0 of the accuracy check (docs/accuracy-check-plan.md): before anyone wears two devices for + * a week, find out what each app actually writes to Health Connect, how often, and how late. Pure — + * no Health Connect or Room imports — so the rules are unit-testable; [ReferenceSourceScanner] + * feeds it. + * + * It keeps counts and timings, never values: the only values it holds are heart-rate samples for + * the echo check, and those don't leave [ReferenceSurveyBuilder.build]. + */ + +/** `Metadata.device`, flattened. [type] is a `Device.TYPE_*` constant. */ +data class DeviceInfo(val manufacturer: String?, val model: String?, val type: Int) + +data class TimedValue(val at: Long, val value: Double) + +/** One Health Connect record, reduced to what the survey needs. Times are epoch millis. */ +data class SurveyRecord( + val packageName: String, + val metric: ReferenceMetric, + /** Sample instants (a series record's samples; an interval record's start). */ + val sampleTimes: List, + val endTime: Long, + val lastModified: Long, + val device: DeviceInfo?, + /** `SleepSessionRecord.STAGE_TYPE_*` values present, for sleep records. */ + val sleepStageTypes: Set = emptySet(), + /** Heart-rate samples, for the echo check only. */ + val heartRate: List = emptyList(), +) + +data class MetricSurvey( + val metric: ReferenceMetric, + val recordCount: Int, + val sampleCount: Int, + val firstAt: Long, + val lastAt: Long, + /** Median gap between consecutive samples; null with fewer than two distinct instants. */ + val medianIntervalMs: Long?, + /** + * Median of `lastModifiedTime - endTime`: how long after the data's own time it reached + * Health Connect. This is the sync lag of a bridge like Health Sync, and it's what decides + * when a check day can be scored. + */ + val medianDeliveryDelayMs: Long, + val sleepStageTypes: Set, +) + +/** + * Whether this source's heart rate looks like PulseLoop's own coming back: the share of its + * samples that match a ring sample to the second and the beat. A bridge syncing both ways + * (Health Connect → Huawei Health → Health Connect) re-publishes PulseLoop's export under its own + * package, which the origin filter can't catch. Only catches exact echoes; a bridge that rounds + * or re-times samples on the way through would slip past. + */ +data class EchoCheck(val compared: Int, val matching: Int) { + val share: Double get() = if (compared == 0) 0.0 else matching.toDouble() / compared + val looksLikeEcho: Boolean get() = compared >= MIN_COMPARED && share >= ECHO_SHARE + + companion object { + const val MIN_COMPARED = 50 + /** Two independent sensors agree to the beat and the second on a few percent of samples + * at most; an echo matches nearly all of them. */ + const val ECHO_SHARE = 0.5 + } +} + +data class ReferenceSourceSurvey( + val packageName: String, + val metrics: List, + val devices: Set, + val echo: EchoCheck?, +) { + val totalSamples: Int get() = metrics.sumOf { it.sampleCount } + fun metric(m: ReferenceMetric): MetricSurvey? = metrics.firstOrNull { it.metric == m } +} + +class ReferenceSurveyBuilder(private val ownPackage: String) { + + private class Acc { + var records = 0 + val sampleTimes = mutableListOf() + val delays = mutableListOf() + val stageTypes = mutableSetOf() + } + + private val bySource = linkedMapOf>() + private val devices = mutableMapOf>() + private val heartRate = mutableMapOf>() + + /** Adds one record. PulseLoop's own records are dropped here, so no caller can forget to. */ + fun add(r: SurveyRecord) { + if (r.packageName == ownPackage) return + val acc = bySource.getOrPut(r.packageName) { linkedMapOf() }.getOrPut(r.metric) { Acc() } + acc.records++ + acc.sampleTimes += r.sampleTimes + acc.delays += (r.lastModified - r.endTime).coerceAtLeast(0) + acc.stageTypes += r.sleepStageTypes + r.device?.let { devices.getOrPut(r.packageName) { mutableSetOf() } += it } + if (r.heartRate.isNotEmpty()) heartRate.getOrPut(r.packageName) { mutableListOf() } += r.heartRate + } + + /** Sources with the most data first. [ringHeartRate] is the ring's own stored HR, for the echo check. */ + fun build(ringHeartRate: List = emptyList()): List { + val ring = ringHeartRate.sortedBy { it.at } + return bySource.map { (pkg, metrics) -> + ReferenceSourceSurvey( + packageName = pkg, + metrics = ReferenceMetric.entries.mapNotNull { m -> metrics[m]?.let { summarize(m, it) } }, + devices = devices[pkg].orEmpty(), + echo = heartRate[pkg]?.takeIf { ring.isNotEmpty() }?.let { echoCheck(it, ring) }, + ) + }.sortedByDescending { it.totalSamples } + } + + private fun summarize(metric: ReferenceMetric, acc: Acc): MetricSurvey { + val times = acc.sampleTimes.sorted() + return MetricSurvey( + metric = metric, + recordCount = acc.records, + sampleCount = times.size, + firstAt = times.firstOrNull() ?: 0L, + lastAt = times.lastOrNull() ?: 0L, + medianIntervalMs = medianInterval(times), + medianDeliveryDelayMs = median(acc.delays.sorted()) ?: 0L, + sleepStageTypes = acc.stageTypes.toSet(), + ) + } + + companion object { + const val ECHO_TIME_TOLERANCE_MS = 1_000L + const val ECHO_VALUE_TOLERANCE = 0.5 + + /** Median positive gap between sorted instants; duplicates (two records stamped at the + * same instant) are not a zero-length cadence. */ + fun medianInterval(sortedTimes: List): Long? = + median(sortedTimes.zipWithNext { a, b -> b - a }.filter { it > 0 }.sorted()) + + fun median(sorted: List): Long? = when { + sorted.isEmpty() -> null + sorted.size % 2 == 1 -> sorted[sorted.size / 2] + else -> (sorted[sorted.size / 2 - 1] + sorted[sorted.size / 2]) / 2 + } + + /** [ring] must be sorted by time. */ + fun echoCheck(reference: List, ring: List): EchoCheck { + var matching = 0 + for (s in reference) { + var i = lowerBound(ring, s.at - ECHO_TIME_TOLERANCE_MS) + while (i < ring.size && ring[i].at <= s.at + ECHO_TIME_TOLERANCE_MS) { + if (abs(ring[i].value - s.value) < ECHO_VALUE_TOLERANCE) { matching++; break } + i++ + } + } + return EchoCheck(compared = reference.size, matching = matching) + } + + private fun lowerBound(sorted: List, at: Long): Int { + var lo = 0 + var hi = sorted.size + while (lo < hi) { + val mid = (lo + hi) ushr 1 + if (sorted[mid].at < at) lo = mid + 1 else hi = mid + } + return lo + } + } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurveyText.kt b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurveyText.kt new file mode 100644 index 00000000..9a810a8f --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/ReferenceSurveyText.kt @@ -0,0 +1,135 @@ +package com.pulseloop.health.accuracy + +import android.content.Context + +/** + * Wording for the reference-source survey, shared by the screen and its "Copy summary" text. + * Pure apart from [ReferenceAppLabels.label]'s PackageManager fallback. + */ +object ReferenceSurveyText { + + fun duration(ms: Long): String { + val minutes = ms / 60_000 + return when { + ms < 60_000 -> "${ms / 1000} s" + minutes < 90 -> "$minutes min" + minutes < 48 * 60 -> "%.1f h".format(minutes / 60.0) + else -> "${minutes / (24 * 60)} days" + } + } + + /** "every 5 min" — or "about daily" for once-a-night records like sleep and resting HR. */ + fun cadence(m: MetricSurvey): String = when (val i = m.medianIntervalMs) { + null -> "single record" + in 20L * 3_600_000..30L * 3_600_000 -> "about daily" + else -> "every ${duration(i)}" + } + + /** `Device.TYPE_*` → word. Constants as published in connect-client 1.1.0. */ + fun deviceType(type: Int): String? = when (type) { + 1 -> "watch" + 2 -> "phone" + 3 -> "scale" + 4 -> "ring" + 5 -> "head-mounted" + 6 -> "fitness band" + 7 -> "chest strap" + 8 -> "smart display" + else -> null + } + + fun device(d: DeviceInfo): String = + listOfNotNull(d.manufacturer?.takeIf { it.isNotBlank() }, d.model?.takeIf { it.isNotBlank() }, deviceType(d.type)?.let { "($it)" }) + .joinToString(" ").ifEmpty { "unnamed device" } + + /** `SleepSessionRecord.STAGE_TYPE_*` → word. */ + fun sleepStage(type: Int): String = when (type) { + 1 -> "awake" + 2 -> "sleeping (no stages)" + 3 -> "out of bed" + 4 -> "light" + 5 -> "deep" + 6 -> "REM" + 7 -> "awake in bed" + else -> "unknown" + } + + /** True when the sleep data has real stages, not just "asleep". */ + fun hasSleepStages(m: MetricSurvey): Boolean = m.sleepStageTypes.any { it in setOf(4, 5, 6) } + + /** + * Plain-text summary for "Copy summary" — something a user can paste into an issue. Counts, + * cadences, delays, device names and stage *types* only: no readings, in line with the + * diagnostics export's rule that health values don't go into text people paste publicly. + */ + fun render( + sources: List, + lookbackDays: Long, + labelFor: (String) -> String, + unreadable: Set, + ): String = buildString { + appendLine("PulseLoop accuracy check — Health Connect sources, last $lookbackDays days") + if (sources.isEmpty()) appendLine("No other app wrote readable data.") + for (s in sources) { + appendLine() + appendLine("${labelFor(s.packageName)} (${s.packageName})") + if (s.devices.isEmpty()) appendLine(" device: not recorded") + else appendLine(" device: " + s.devices.joinToString("; ") { device(it) }) + for (m in s.metrics) { + append(" ${m.metric.label}: ${m.recordCount} records, ${m.sampleCount} samples, ${cadence(m)}, ") + append("arrives ${duration(m.medianDeliveryDelayMs)} late (median)") + if (m.metric == ReferenceMetric.SLEEP) { + append(", stages: " + m.sleepStageTypes.sorted().joinToString(", ") { sleepStage(it) }) + } + appendLine() + } + s.echo?.let { + appendLine(" echo check: ${it.matching}/${it.compared} heart-rate samples match the ring exactly" + + if (it.looksLikeEcho) " — LOOKS LIKE PULSELOOP'S OWN DATA" else "") + } + } + if (unreadable.isNotEmpty()) { + appendLine() + appendLine("Not readable (permission not granted): " + unreadable.joinToString(", ") { it.label }) + } + }.trimEnd() +} + +/** + * Human names for the apps behind Health Connect `DataOrigin`s. PackageManager can't see most of + * them — Android 11+ package visibility, and the manifest's `` names only Health Connect + * itself — so the common health apps are named here and anything else falls back to the package + * name. Health Sync is listed because it's a bridge: its records are someone else's device. + */ +object ReferenceAppLabels { + + val KNOWN: Map = mapOf( + "nl.appyhapps.healthsync" to "Health Sync", + "com.fitbit.FitbitMobile" to "Fitbit", + "com.google.android.apps.fitness" to "Google Fit", + "com.google.android.apps.healthdata" to "Health Connect", + "com.sec.android.app.shealth" to "Samsung Health", + "com.huawei.health" to "Huawei Health", + "com.garmin.android.apps.connectmobile" to "Garmin Connect", + "com.ouraring.oura" to "Oura", + "com.withings.wiscale2" to "Withings", + "com.xiaomi.wearable" to "Mi Fitness", + "com.mi.health" to "Mi Fitness", + "com.zepp.health" to "Zepp", + "com.huami.watch.hmwatchmanager" to "Zepp", + "com.polar.polarflow" to "Polar Flow", + "com.suunto.android" to "Suunto", + "com.whoop.android" to "WHOOP", + "com.coros.coros" to "COROS", + "com.amazfit" to "Amazfit", + ) + + /** Bridges re-publish another app's data under their own package. */ + val BRIDGES: Set = setOf("nl.appyhapps.healthsync") + + fun label(context: Context, packageName: String): String = + KNOWN[packageName] ?: runCatching { + val pm = context.packageManager + pm.getApplicationLabel(pm.getApplicationInfo(packageName, 0)).toString() + }.getOrNull()?.takeIf { it.isNotBlank() && it != packageName } ?: packageName +} diff --git a/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt b/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt index b207aac1..9a58bc6f 100644 --- a/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt +++ b/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt @@ -628,6 +628,9 @@ fun PulseLoopApp() { paddedComposable("settings/health-connect") { HealthConnectSettingsScreen(onBack = { navController.popBackStack() }) } + paddedComposable("settings/accuracy-check") { + AccuracyCheckSettingsScreen(onBack = { navController.popBackStack() }) + } paddedComposable("settings/nutrition") { NutritionSettingsScreen( onBack = { navController.popBackStack() }, diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt new file mode 100644 index 00000000..eb6b4a70 --- /dev/null +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt @@ -0,0 +1,203 @@ +package com.pulseloop.ui.screens + +import android.content.ClipData +import android.content.ClipboardManager +import android.content.Context +import androidx.activity.compose.rememberLauncherForActivityResult +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Arrangement +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.Row +import androidx.compose.foundation.layout.fillMaxWidth +import androidx.compose.foundation.layout.padding +import androidx.compose.foundation.layout.size +import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.material3.Button +import androidx.compose.material3.CircularProgressIndicator +import androidx.compose.material3.OutlinedButton +import androidx.compose.material3.Text +import androidx.compose.runtime.Composable +import androidx.compose.runtime.LaunchedEffect +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope +import androidx.compose.runtime.setValue +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.draw.clip +import androidx.compose.ui.platform.LocalContext +import androidx.compose.ui.text.font.FontWeight +import androidx.compose.ui.unit.dp +import androidx.compose.ui.unit.sp +import androidx.health.connect.client.PermissionController +import com.pulseloop.health.HealthConnectAvailability +import com.pulseloop.health.HealthConnectSdk +import com.pulseloop.health.accuracy.AccuracyCheckPermissions +import com.pulseloop.health.accuracy.MetricSurvey +import com.pulseloop.health.accuracy.ReferenceAppLabels +import com.pulseloop.health.accuracy.ReferenceMetric +import com.pulseloop.health.accuracy.ReferenceSourceScanner +import com.pulseloop.health.accuracy.ReferenceSourceSurvey +import com.pulseloop.health.accuracy.ReferenceSurveyText +import com.pulseloop.ui.theme.PulseColors +import kotlinx.coroutines.launch +import java.time.Instant +import java.time.ZoneId +import java.time.format.DateTimeFormatter + +/** + * Settings → Accuracy check, Phase 0 (docs/accuracy-check-plan.md): grant read access, then scan + * Health Connect for which apps write what, how often and how late. Starting a check comes in a + * later phase; this screen is useful on its own, and it answers the questions the later phases + * depend on (does Health Sync name the device, how sparse is its heart rate, how far behind is it). + */ +@Composable +fun AccuracyCheckSettingsScreen(onBack: () -> Unit) { + val context = LocalContext.current + val scope = rememberCoroutineScope() + val available = remember { HealthConnectSdk.availability(context) == HealthConnectAvailability.AVAILABLE } + var granted by remember { mutableStateOf>(emptySet()) } + var scanning by remember { mutableStateOf(false) } + var result by remember { mutableStateOf(null) } + var note by remember { mutableStateOf(null) } + + fun scan() { + scanning = true + note = null + scope.launch { + when (val r = runCatching { ReferenceSourceScanner.scan(context) }.getOrNull()) { + is ReferenceSourceScanner.Result.Done -> result = r + ReferenceSourceScanner.Result.Unavailable -> note = "Health Connect isn't available on this phone." + null -> note = "The scan failed. Try again in a moment." + } + scanning = false + } + } + + LaunchedEffect(Unit) { granted = ReferenceSourceScanner.grantedPermissions(context) } + val readable = AccuracyCheckPermissions.readable(granted) + + val launcher = rememberLauncherForActivityResult(PermissionController.createRequestPermissionResultContract()) { got -> + granted = got + if (AccuracyCheckPermissions.readable(got).isEmpty()) { + note = "No access granted. You can allow it in Health Connect's settings." + } else scan() + } + + SettingsSubScreen(title = "Accuracy check", onBack = onBack) { + AccuracyCard { + Text("Compare your ring with another device", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + Text( + "Wear the ring and a watch or band you trust for a few days. PulseLoop reads that device's data from " + + "Health Connect and shows where the ring agrees and where it falls short.", + fontSize = 13.sp, color = PulseColors.textSecondary, + ) + Text( + "First step: see which apps share what with Health Connect. Starting a check comes in a later update.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + if (!available) { + Text("Health Connect isn't available on this phone.", fontSize = 12.sp, color = PulseColors.danger) + } else { + Row(horizontalArrangement = Arrangement.spacedBy(8.dp), verticalAlignment = Alignment.CenterVertically) { + if (readable.size < ReferenceMetric.entries.size) { + Button(onClick = { launcher.launch(AccuracyCheckPermissions.all) }, enabled = !scanning) { + Text(if (readable.isEmpty()) "Allow access" else "Allow more") + } + } + if (readable.isNotEmpty()) { + OutlinedButton(onClick = { scan() }, enabled = !scanning) { Text("Scan last ${ReferenceSourceScanner.LOOKBACK_DAYS} days") } + } + if (scanning) CircularProgressIndicator(Modifier.size(20.dp), strokeWidth = 2.dp) + } + } + note?.let { Text(it, fontSize = 12.sp, color = PulseColors.warning) } + } + + val r = result + if (r != null) { + if (r.sources.isEmpty()) { + AccuracyCard { + Text("No other app wrote readable data in the last ${ReferenceSourceScanner.LOOKBACK_DAYS} days.", fontSize = 13.sp, color = PulseColors.textSecondary) + Text( + "If your watch syncs through an app like Health Sync, check that it's set to write to Health Connect.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + } + } + r.sources.forEach { SourceCard(context, it) } + if (r.unreadable.isNotEmpty() || r.failed.isNotEmpty()) { + AccuracyCard { + if (r.unreadable.isNotEmpty()) { + Text("Not allowed to read: " + r.unreadable.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.textMuted) + } + if (r.failed.isNotEmpty()) { + Text("Couldn't read: " + r.failed.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.warning) + } + } + } + OutlinedButton(onClick = { + val text = ReferenceSurveyText.render(r.sources, ReferenceSourceScanner.LOOKBACK_DAYS, { ReferenceAppLabels.label(context, it) }, r.unreadable) + (context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager) + .setPrimaryClip(ClipData.newPlainText("Accuracy check sources", text)) + note = "Summary copied. It holds counts and timings only, no readings." + }, modifier = Modifier.fillMaxWidth()) { Text("Copy summary") } + } + } +} + +@Composable +private fun SourceCard(context: Context, s: ReferenceSourceSurvey) { + AccuracyCard { + Text(ReferenceAppLabels.label(context, s.packageName), fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + Text(s.packageName, fontSize = 11.sp, color = PulseColors.textMuted) + if (s.packageName in ReferenceAppLabels.BRIDGES) { + Text( + "A bridge app: it copies another app's data (for example Huawei Health) into Health Connect.", + fontSize = 12.sp, color = PulseColors.textSecondary, + ) + } + Text( + if (s.devices.isEmpty()) "Device: not recorded" + else "Device: " + s.devices.joinToString("; ") { ReferenceSurveyText.device(it) }, + fontSize = 12.sp, color = PulseColors.textSecondary, + ) + s.echo?.takeIf { it.looksLikeEcho }?.let { + Text( + "${it.matching} of ${it.compared} heart-rate samples match your ring exactly. This looks like PulseLoop's own " + + "data coming back — check that the app syncs from your watch only, not from Health Connect.", + fontSize = 12.sp, color = PulseColors.danger, + ) + } + s.metrics.forEach { MetricRow(it) } + } +} + +@Composable +private fun MetricRow(m: MetricSurvey) { + val last = Instant.ofEpochMilli(m.lastAt).atZone(ZoneId.systemDefault()).format(DateTimeFormatter.ofPattern("d MMM HH:mm")) + Column(Modifier.fillMaxWidth().padding(top = 4.dp)) { + Text(m.metric.label, fontSize = 13.sp, fontWeight = FontWeight.SemiBold, color = PulseColors.textPrimary) + Text( + "${m.sampleCount} samples, ${ReferenceSurveyText.cadence(m)} · latest $last · " + + "arrives ~${ReferenceSurveyText.duration(m.medianDeliveryDelayMs)} late", + fontSize = 12.sp, color = PulseColors.textSecondary, + ) + if (m.metric == ReferenceMetric.SLEEP) { + Text( + if (ReferenceSurveyText.hasSleepStages(m)) "With stages: " + m.sleepStageTypes.sorted().joinToString(", ") { ReferenceSurveyText.sleepStage(it) } + else "No sleep stages, only time asleep", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + } + } +} + +@Composable +private fun AccuracyCard(content: @Composable () -> Unit) { + Column( + Modifier.fillMaxWidth().clip(RoundedCornerShape(8.dp)).background(PulseColors.card).padding(16.dp), + verticalArrangement = Arrangement.spacedBy(8.dp), + ) { content() } +} diff --git a/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt index 80eca212..d7390566 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt @@ -170,6 +170,9 @@ fun SettingsScreen( add(SettingsRowItem(Icons.Filled.Sync, PulseColors.success, "Health Connect") { navigate("settings/health-connect") }) + add(SettingsRowItem(Icons.Filled.Verified, PulseColors.info, "Accuracy check") { + navigate("settings/accuracy-check") + }) add(SettingsRowItem(Icons.Filled.Info, PulseColors.textMuted, "About PulseLoop") { navigate("settings/about") }) diff --git a/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt b/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt index d1c8d51c..1dff1b3d 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt @@ -102,7 +102,7 @@ import kotlinx.coroutines.launch /** Pushed-screen chrome shared by every settings detail screen: back arrow + title + scroll column. */ @OptIn(ExperimentalMaterial3Api::class) @Composable -private fun SettingsSubScreen( +internal fun SettingsSubScreen( title: String, onBack: () -> Unit, bottomOverlay: (@Composable BoxScope.() -> Unit)? = null, diff --git a/app/src/test/java/com/pulseloop/health/accuracy/ReferenceSurveyTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/ReferenceSurveyTest.kt new file mode 100644 index 00000000..9768db42 --- /dev/null +++ b/app/src/test/java/com/pulseloop/health/accuracy/ReferenceSurveyTest.kt @@ -0,0 +1,136 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.health.HealthConnectBodyImport +import com.pulseloop.health.HealthConnectPermissionReconcile +import com.pulseloop.health.HealthConnectPermissions +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test + +class ReferenceSurveyTest { + + private val own = "com.pulseloop" + private val sync = "nl.appyhapps.healthsync" + private val min = 60_000L + + private fun hr(pkg: String, times: List, bpm: Double = 60.0, end: Long = times.last(), modified: Long = end) = + SurveyRecord(pkg, ReferenceMetric.HEART_RATE, times, end, modified, null, heartRate = times.map { TimedValue(it, bpm) }) + + @Test + fun ownRecordsNeverBecomeASource() { + val b = ReferenceSurveyBuilder(own) + b.add(hr(own, listOf(0, min))) + b.add(hr(sync, listOf(0, min))) + assertEquals(listOf(sync), b.build().map { it.packageName }) + } + + @Test + fun cadenceIsTheMedianGapAcrossRecordsIgnoringDuplicates() { + val b = ReferenceSurveyBuilder(own) + // Two records, 5-minute samples, one instant written twice, one long overnight gap. + b.add(hr(sync, listOf(0, 5 * min, 10 * min, 10 * min))) + b.add(hr(sync, listOf(15 * min, 20 * min, 600 * min))) + val m = b.build().single().metric(ReferenceMetric.HEART_RATE)!! + assertEquals(7, m.sampleCount) + assertEquals(5 * min, m.medianIntervalMs) + assertEquals(0L, m.firstAt) + assertEquals(600 * min, m.lastAt) + } + + @Test + fun aSingleSampleHasNoCadence() { + assertNull(ReferenceSurveyBuilder.medianInterval(listOf(42L))) + assertNull(ReferenceSurveyBuilder.medianInterval(listOf(42L, 42L))) + } + + @Test + fun deliveryDelayIsLastModifiedMinusEnd_neverNegative() { + val b = ReferenceSurveyBuilder(own) + b.add(hr(sync, listOf(0), end = 0, modified = 30 * min)) + b.add(hr(sync, listOf(min), end = min, modified = min + 90 * min)) + b.add(hr(sync, listOf(2 * min), end = 2 * min, modified = 0)) // clock skew: clamp + assertEquals(30 * min, b.build().single().metric(ReferenceMetric.HEART_RATE)!!.medianDeliveryDelayMs) + } + + @Test + fun sourcesAreOrderedByVolumeAndMetricsByDisplayOrder() { + val b = ReferenceSurveyBuilder(own) + b.add(SurveyRecord("small", ReferenceMetric.STEPS, listOf(0), min, min, null)) + b.add(SurveyRecord(sync, ReferenceMetric.SLEEP, listOf(0), min, min, null, sleepStageTypes = setOf(4, 5))) + b.add(hr(sync, listOf(0, min, 2 * min))) + val out = b.build() + assertEquals(listOf(sync, "small"), out.map { it.packageName }) + assertEquals(listOf(ReferenceMetric.HEART_RATE, ReferenceMetric.SLEEP), out.first().metrics.map { it.metric }) + assertEquals(setOf(4, 5), out.first().metric(ReferenceMetric.SLEEP)!!.sleepStageTypes) + } + + @Test + fun devicesAreCollectedPerSource() { + val b = ReferenceSurveyBuilder(own) + val watch = DeviceInfo("HUAWEI", "WATCH GT 4", 1) + b.add(hr(sync, listOf(0)).copy(device = watch)) + b.add(hr(sync, listOf(min)).copy(device = watch)) + assertEquals(setOf(watch), b.build().single().devices) + } + + @Test + fun anEchoOfTheRingsOwnHeartRateIsFlagged() { + val times = (0 until 100).map { it * 5 * min } + val ring = times.map { TimedValue(it + 400, 70.0) } + val b = ReferenceSurveyBuilder(own) + b.add(hr(sync, times, bpm = 70.0)) + val echo = b.build(ring).single().echo!! + assertEquals(100, echo.matching) + assertTrue(echo.looksLikeEcho) + } + + @Test + fun anIndependentDeviceIsNotAnEcho() { + val times = (0 until 100).map { it * 5 * min } + // Same instants, different readings — two real sensors. + val ring = times.map { TimedValue(it, 64.0) } + val b = ReferenceSurveyBuilder(own) + b.add(hr(sync, times.map { it + 2_000 }, bpm = 64.0)) // and 2 s apart + b.add(hr("other", times, bpm = 70.0)) + val bySource = b.build(ring).associateBy { it.packageName } + assertFalse(bySource.getValue(sync).echo!!.looksLikeEcho) + assertEquals(0, bySource.getValue("other").echo!!.matching) + } + + @Test + fun tooFewSamplesCanNeverLookLikeAnEcho() { + assertFalse(EchoCheck(compared = 10, matching = 10).looksLikeEcho) + } + + @Test + fun noRingHeartRateMeansNoEchoCheck() { + val b = ReferenceSurveyBuilder(own) + b.add(hr(sync, listOf(0, min))) + assertNull(b.build().single().echo) + } + + @Test + fun summaryTextHoldsNoReadings() { + val b = ReferenceSurveyBuilder(own) + b.add(hr(sync, listOf(0, 5 * min, 10 * min), bpm = 137.0).copy(device = DeviceInfo("HUAWEI", "WATCH GT 4", 1))) + val text = ReferenceSurveyText.render(b.build(), 7, { ReferenceAppLabels.KNOWN[it] ?: it }, setOf(ReferenceMetric.HRV)) + assertTrue(text, text.contains("Health Sync (nl.appyhapps.healthsync)")) + assertTrue(text, text.contains("HUAWEI WATCH GT 4 (watch)")) + assertTrue(text, text.contains("every 5 min")) + assertTrue(text, text.contains("Not readable (permission not granted): HRV")) + assertFalse(text, text.contains("137")) + } + + @Test + fun readPermissionsAreTheirOwnSet() { + assertEquals(ReferenceMetric.entries.size, AccuracyCheckPermissions.all.size) + assertTrue(AccuracyCheckPermissions.all.all { it.startsWith("android.permission.health.READ_") }) + assertTrue(AccuracyCheckPermissions.all.none { it in HealthConnectBodyImport.permissions }) + // The export's reconcile must not count an accuracy-check grant as an export grant. + assertTrue(HealthConnectPermissionReconcile.storedSetOf(AccuracyCheckPermissions.all).isEmpty()) + assertTrue(AccuracyCheckPermissions.all.none { it in HealthConnectPermissions.all }) + assertTrue("android.permission.health.READ_HEART_RATE_VARIABILITY" in AccuracyCheckPermissions.all) + } +} diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md index a5c1b746..3b612e16 100644 --- a/docs/accuracy-check-plan.md +++ b/docs/accuracy-check-plan.md @@ -1,6 +1,6 @@ # Accuracy check — compare the ring against another device via Health Connect -Status: **plan, nothing implemented.** Date: 2026-10-21. +Status: **Phase 0 implemented** (2026-10-21), waiting on a real-device scan. Later phases are plan only. ## The idea @@ -318,6 +318,14 @@ say it is derived"* (#67), and the ring re-supplying its own history on every sy user can see what each app actually shares with Health Connect. *Verify on real devices which types Fitbit and Samsung Health actually write; this decides what the report can cover.* + *Done:* `health/accuracy/` — `AccuracyCheckPermissions` (8 READ_* types), `ReferenceSurvey` + (pure: per source and type, record/sample counts, median cadence, median delivery delay = + `lastModifiedTime − endTime`, devices from `Metadata.device`, sleep stage types, and the HR + echo check), `ReferenceSourceScanner` (foreground read of the last 7 days), + `ReferenceSurveyText` (wording + "Copy summary", counts and timings only). Screen: + Settings → Accuracy check (`AccuracyCheckUi.kt`). Nothing is stored yet. **Next:** run the + scan on the Huawei/Health Sync setup and paste the copied summary; it answers the four + Health Sync questions under Open questions. 1. **Session lifecycle + per-type export pause**: table, the exporter's per-row pause gate that holds watermarks, daily refresh of the pause set, export-screen state, end job, notification, resume dialog with the per-kind skip, early end on a ring change. Unit-test the skip and that From e3ca71fc6a4856652e9771c5f9a903ef8c3b843d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 15:55:03 +0000 Subject: [PATCH 5/9] Accuracy check Phase 1: run a check and hold back duplicate Health Connect 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. --- app/src/main/AndroidManifest.xml | 2 + .../main/java/com/pulseloop/MainActivity.kt | 5 + .../com/pulseloop/PulseLoopApplication.kt | 3 + .../java/com/pulseloop/data/DataArchive.kt | 33 ++ .../com/pulseloop/data/DataArchiveService.kt | 63 ++++ .../com/pulseloop/data/PulseLoopDatabase.kt | 47 ++- .../main/java/com/pulseloop/data/dao/Daos.kt | 68 ++++ .../pulseloop/data/entity/AccuracyEntities.kt | 122 +++++++ .../com/pulseloop/data/entity/CoreEntities.kt | 6 + .../pulseloop/health/HealthConnectExporter.kt | 51 ++- .../health/HealthConnectPrefsStore.kt | 24 ++ .../accuracy/AccuracyCheckController.kt | 206 +++++++++++ .../accuracy/AccuracyCheckPermissions.kt | 7 + .../health/accuracy/AccuracyCheckWorker.kt | 119 +++++++ .../health/accuracy/AccuracyRingWatcher.kt | 30 ++ .../pulseloop/health/accuracy/ExportPause.kt | 165 +++++++++ .../pulseloop/ui/screens/AccuracyCheckUi.kt | 331 +++++++++++++++--- .../pulseloop/ui/screens/AccuracyReportUi.kt | 9 + .../pulseloop/ui/screens/SettingsScreen.kt | 9 +- .../ui/screens/SettingsSubScreens.kt | 16 + .../com/pulseloop/ui/screens/TodayScreen.kt | 4 + .../health/HealthConnectPrefsStoreTest.kt | 23 ++ .../health/accuracy/ExportPauseTest.kt | 130 +++++++ 23 files changed, 1414 insertions(+), 59 deletions(-) create mode 100644 app/src/main/java/com/pulseloop/data/entity/AccuracyEntities.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckController.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckWorker.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyRingWatcher.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/ExportPause.kt create mode 100644 app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt create mode 100644 app/src/test/java/com/pulseloop/health/accuracy/ExportPauseTest.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index f00ad259..d3cd4dd1 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -86,6 +86,8 @@ + + = emptyList(), val medDoses: List = emptyList(), + /** + * Accuracy checks (v36). Carried because they hold the export exclusions too: without them a + * restore would forget which days were held back from Health Connect, and the next export + * pass would write the check window's duplicates after all. + */ + val accuracyChecks: List = emptyList(), + val accuracyPausedUnits: List = emptyList(), + val accuracyCheckDays: List = emptyList(), + val accuracyCorrections: List = emptyList(), +) + +@Serializable data class AccuracyCheckDTO( + val id: String, val deviceKey: String, val deviceLabel: String, val referencePackage: String, + val referenceLabel: String, val startedAt: Long, val plannedEndAt: Long, val endedAt: Long? = null, + val state: String, val endReason: String? = null, val resumeChoice: String? = null, + val bandsRaw: String? = null, val pauseRefreshedAt: Long? = null, val scoredAt: Long? = null, + val firmware: String? = null, +) + +@Serializable data class AccuracyPausedUnitDTO(val checkId: String, val unit: String, val pausedFrom: Long) + +@Serializable data class AccuracyCheckDayDTO( + val checkId: String, val metric: String, val day: Long, val ringValue: Double? = null, + val refValue: Double? = null, val pairs: Int = 0, val sumDiff: Double = 0.0, val sumSqDiff: Double = 0.0, + val sumAbsDiff: Double = 0.0, val inBand: Int = 0, val valid: Boolean = true, val note: String? = null, + val computedAt: Long, +) + +@Serializable data class AccuracyCorrectionDTO( + val deviceKey: String, val metric: String, val kind: String, val value: Double, val fittedValue: Double, + val fromCheckId: String, val enabled: Boolean = true, val firmware: String? = null, + val createdAt: Long, val updatedAt: Long, ) @Serializable data class FoodPreferenceDTO( @@ -119,6 +151,7 @@ data class PulseArchive( * buckets back into the day. */ val deletedSteps: Int = 0, val deletedDistanceMeters: Double = 0.0, val estimatedActiveCalories: Double? = null, + val estimatedActiveCaloriesAdjusted: Double? = null, ) @Serializable data class ActivityBucketDTO( diff --git a/app/src/main/java/com/pulseloop/data/DataArchiveService.kt b/app/src/main/java/com/pulseloop/data/DataArchiveService.kt index ba2a5c90..d24bfba3 100644 --- a/app/src/main/java/com/pulseloop/data/DataArchiveService.kt +++ b/app/src/main/java/com/pulseloop/data/DataArchiveService.kt @@ -80,6 +80,7 @@ object DataArchiveService { syncedAt = c.longOrNull("syncedAt"), createdAt = c.long("createdAt"), updatedAt = c.long("updatedAt"), estimatedActiveCalories = c.dblOrNull("estimatedActiveCalories"), + estimatedActiveCaloriesAdjusted = c.dblOrNull("estimatedActiveCaloriesAdjusted"), deletedSteps = c.int_("deletedSteps"), deletedDistanceMeters = c.dbl("deletedDistanceMeters"), ) @@ -333,6 +334,36 @@ object DataArchiveService { MedDTO(id = c.str("id"), name = c.str("name"), dose = c.strOrNull("dose"), kind = c.str("kind"), timesCsv = c.str("timesCsv"), active = (c.intOrNull("active") ?: 1) == 1, createdAt = c.long("createdAt")) }, + accuracyChecks = collect("accuracy_checks") { c -> + AccuracyCheckDTO( + id = c.str("id"), deviceKey = c.str("deviceKey"), deviceLabel = c.str("deviceLabel"), + referencePackage = c.str("referencePackage"), referenceLabel = c.str("referenceLabel"), + startedAt = c.long("startedAt"), plannedEndAt = c.long("plannedEndAt"), endedAt = c.longOrNull("endedAt"), + state = c.str("state"), endReason = c.strOrNull("endReason"), resumeChoice = c.strOrNull("resumeChoice"), + bandsRaw = c.strOrNull("bandsRaw"), pauseRefreshedAt = c.longOrNull("pauseRefreshedAt"), + scoredAt = c.longOrNull("scoredAt"), firmware = c.strOrNull("firmware"), + ) + }, + accuracyPausedUnits = collect("accuracy_paused_units") { c -> + AccuracyPausedUnitDTO(checkId = c.str("checkId"), unit = c.str("unit"), pausedFrom = c.long("pausedFrom")) + }, + accuracyCheckDays = collect("accuracy_check_days") { c -> + AccuracyCheckDayDTO( + checkId = c.str("checkId"), metric = c.str("metric"), day = c.long("day"), + ringValue = c.dblOrNull("ringValue"), refValue = c.dblOrNull("refValue"), pairs = c.int_("pairs"), + sumDiff = c.dbl("sumDiff"), sumSqDiff = c.dbl("sumSqDiff"), sumAbsDiff = c.dbl("sumAbsDiff"), + inBand = c.int_("inBand"), valid = c.bool("valid"), note = c.strOrNull("note"), + computedAt = c.long("computedAt"), + ) + }, + accuracyCorrections = collect("accuracy_corrections") { c -> + AccuracyCorrectionDTO( + deviceKey = c.str("deviceKey"), metric = c.str("metric"), kind = c.str("kind"), + value = c.dbl("value"), fittedValue = c.dbl("fittedValue"), fromCheckId = c.str("fromCheckId"), + enabled = c.bool("enabled"), firmware = c.strOrNull("firmware"), + createdAt = c.long("createdAt"), updatedAt = c.long("updatedAt"), + ) + }, medDoses = collect("med_doses") { c -> MedDoseDTO(id = c.str("id"), medId = c.str("medId"), day = c.long("day"), time = c.str("time"), status = c.str("status"), at = c.long("at")) }, @@ -446,6 +477,37 @@ object DataArchiveService { for (m in archive.meds) { db.medDao().upsert(MedEntity(id = m.id, name = m.name, dose = m.dose, kind = m.kind, timesCsv = m.timesCsv, active = m.active, createdAt = m.createdAt)) } + // Accuracy checks before anything can export against them (see PulseArchive.accuracyChecks). + for (a in archive.accuracyChecks) { + db.accuracyDao().upsert(AccuracyCheckEntity( + id = a.id, deviceKey = a.deviceKey, deviceLabel = a.deviceLabel, referencePackage = a.referencePackage, + referenceLabel = a.referenceLabel, startedAt = a.startedAt, plannedEndAt = a.plannedEndAt, + endedAt = a.endedAt, state = a.state, endReason = a.endReason, resumeChoice = a.resumeChoice, + bandsRaw = a.bandsRaw, pauseRefreshedAt = a.pauseRefreshedAt, scoredAt = a.scoredAt, firmware = a.firmware, + )) + } + if (archive.accuracyPausedUnits.isNotEmpty()) { + db.accuracyDao().insertPausedUnits(archive.accuracyPausedUnits.map { + AccuracyPausedUnitEntity(checkId = it.checkId, unit = it.unit, pausedFrom = it.pausedFrom) + }) + } + if (archive.accuracyCheckDays.isNotEmpty()) { + db.accuracyDao().upsertDays(archive.accuracyCheckDays.map { + AccuracyCheckDayEntity( + checkId = it.checkId, metric = it.metric, day = it.day, ringValue = it.ringValue, + refValue = it.refValue, pairs = it.pairs, sumDiff = it.sumDiff, sumSqDiff = it.sumSqDiff, + sumAbsDiff = it.sumAbsDiff, inBand = it.inBand, valid = it.valid, note = it.note, + computedAt = it.computedAt, + ) + }) + } + for (c in archive.accuracyCorrections) { + db.accuracyDao().upsertCorrection(AccuracyCorrectionEntity( + deviceKey = c.deviceKey, metric = c.metric, kind = c.kind, value = c.value, + fittedValue = c.fittedValue, fromCheckId = c.fromCheckId, enabled = c.enabled, + firmware = c.firmware, createdAt = c.createdAt, updatedAt = c.updatedAt, + )) + } for (d in archive.medDoses) { db.medDao().upsertDose(MedDoseEntity(id = d.id, medId = d.medId, day = d.day, time = d.time, status = d.status, at = d.at)) } @@ -480,6 +542,7 @@ object DataArchiveService { source = a.source, syncedAt = a.syncedAt, createdAt = a.createdAt, updatedAt = a.updatedAt, estimatedActiveCalories = a.estimatedActiveCalories, + estimatedActiveCaloriesAdjusted = a.estimatedActiveCaloriesAdjusted, deletedSteps = a.deletedSteps, deletedDistanceMeters = a.deletedDistanceMeters, )) diff --git a/app/src/main/java/com/pulseloop/data/PulseLoopDatabase.kt b/app/src/main/java/com/pulseloop/data/PulseLoopDatabase.kt index e75d500c..a34b9441 100644 --- a/app/src/main/java/com/pulseloop/data/PulseLoopDatabase.kt +++ b/app/src/main/java/com/pulseloop/data/PulseLoopDatabase.kt @@ -52,8 +52,12 @@ import com.pulseloop.data.entity.* PeriodEntity::class, MedEntity::class, MedDoseEntity::class, + AccuracyCheckEntity::class, + AccuracyPausedUnitEntity::class, + AccuracyCheckDayEntity::class, + AccuracyCorrectionEntity::class, ], - version = 35, + version = 36, exportSchema = false, ) abstract class PulseLoopDatabase : RoomDatabase() { @@ -88,6 +92,8 @@ abstract class PulseLoopDatabase : RoomDatabase() { abstract fun periodDao(): PeriodDao /** Medications and supplements, and answered doses (v35). */ abstract fun medDao(): MedDao + /** The accuracy check against another device (docs/accuracy-check-plan.md, v36). */ + abstract fun accuracyDao(): AccuracyDao abstract fun coachSummaryDao(): CoachSummaryDao abstract fun wearableLogDao(): WearableLogDao abstract fun rawPacketDao(): RawPacketDao @@ -142,6 +148,7 @@ abstract class PulseLoopDatabase : RoomDatabase() { "findings", "periods", "meds", "med_doses", + "accuracy_checks", "accuracy_paused_units", "accuracy_check_days", "accuracy_corrections", ) @Volatile private var INSTANCE: PulseLoopDatabase? = null @@ -647,6 +654,43 @@ abstract class PulseLoopDatabase : RoomDatabase() { } } + /** + * v35 → v36: the accuracy check (docs/accuracy-check-plan.md) — its checks, the export + * units each one holds back, its scored days, and the per-ring corrections — plus the + * corrected copy of the day's estimated active calories, kept beside the raw one because + * the raw one is what Health Connect receives. + */ + private val MIGRATION_35_36 = object : Migration(35, 36) { + override fun migrate(db: SupportSQLiteDatabase) { + db.execSQL( + "CREATE TABLE IF NOT EXISTS `accuracy_checks` (`id` TEXT NOT NULL, `deviceKey` TEXT NOT NULL, " + + "`deviceLabel` TEXT NOT NULL, `referencePackage` TEXT NOT NULL, `referenceLabel` TEXT NOT NULL, " + + "`startedAt` INTEGER NOT NULL, `plannedEndAt` INTEGER NOT NULL, `endedAt` INTEGER, " + + "`state` TEXT NOT NULL, `endReason` TEXT, `resumeChoice` TEXT, `bandsRaw` TEXT, " + + "`pauseRefreshedAt` INTEGER, `scoredAt` INTEGER, `firmware` TEXT, PRIMARY KEY(`id`))" + ) + db.execSQL("CREATE INDEX IF NOT EXISTS `index_accuracy_checks_state` ON `accuracy_checks` (`state`)") + db.execSQL( + "CREATE TABLE IF NOT EXISTS `accuracy_paused_units` (`checkId` TEXT NOT NULL, `unit` TEXT NOT NULL, " + + "`pausedFrom` INTEGER NOT NULL, PRIMARY KEY(`checkId`, `unit`))" + ) + db.execSQL( + "CREATE TABLE IF NOT EXISTS `accuracy_check_days` (`checkId` TEXT NOT NULL, `metric` TEXT NOT NULL, " + + "`day` INTEGER NOT NULL, `ringValue` REAL, `refValue` REAL, `pairs` INTEGER NOT NULL, " + + "`sumDiff` REAL NOT NULL, `sumSqDiff` REAL NOT NULL, `sumAbsDiff` REAL NOT NULL, " + + "`inBand` INTEGER NOT NULL, `valid` INTEGER NOT NULL, `note` TEXT, `computedAt` INTEGER NOT NULL, " + + "PRIMARY KEY(`checkId`, `metric`, `day`))" + ) + db.execSQL( + "CREATE TABLE IF NOT EXISTS `accuracy_corrections` (`deviceKey` TEXT NOT NULL, `metric` TEXT NOT NULL, " + + "`kind` TEXT NOT NULL, `value` REAL NOT NULL, `fittedValue` REAL NOT NULL, `fromCheckId` TEXT NOT NULL, " + + "`enabled` INTEGER NOT NULL, `firmware` TEXT, `createdAt` INTEGER NOT NULL, `updatedAt` INTEGER NOT NULL, " + + "PRIMARY KEY(`deviceKey`, `metric`))" + ) + db.execSQL("ALTER TABLE `activity_daily` ADD COLUMN `estimatedActiveCaloriesAdjusted` REAL") + } + } + private fun adoptStableMeasurementIdentities(db: SupportSQLiteDatabase) { db.execSQL("DROP INDEX IF EXISTS `index_measurements_kindRaw_timestamp_sourceRaw`") db.execSQL( @@ -748,6 +792,7 @@ abstract class PulseLoopDatabase : RoomDatabase() { MIGRATION_32_33, MIGRATION_33_34, MIGRATION_34_35, + MIGRATION_35_36, ) // Downgrades only (sideloading an older APK). A blanket destructive // fallback would silently wipe every measurement, sleep session, and diff --git a/app/src/main/java/com/pulseloop/data/dao/Daos.kt b/app/src/main/java/com/pulseloop/data/dao/Daos.kt index 947fca8b..3cd75fa7 100644 --- a/app/src/main/java/com/pulseloop/data/dao/Daos.kt +++ b/app/src/main/java/com/pulseloop/data/dao/Daos.kt @@ -1031,3 +1031,71 @@ interface MedDao { @Query("DELETE FROM med_doses WHERE medId = :medId") suspend fun deleteDosesFor(medId: String) } + +/** The accuracy check (docs/accuracy-check-plan.md, v36). */ +@Dao +interface AccuracyDao { + @Query("SELECT * FROM accuracy_checks WHERE state IN ('RUNNING', 'AWAITING_RESUME') ORDER BY startedAt DESC LIMIT 1") + suspend fun open(): AccuracyCheckEntity? + + @Query("SELECT * FROM accuracy_checks WHERE state IN ('RUNNING', 'AWAITING_RESUME') ORDER BY startedAt DESC LIMIT 1") + fun openFlow(): Flow + + @Query("SELECT * FROM accuracy_checks ORDER BY startedAt DESC") + fun allFlow(): Flow> + + @Query("SELECT * FROM accuracy_checks ORDER BY startedAt DESC") + suspend fun all(): List + + @Query("SELECT * FROM accuracy_checks WHERE id = :id") + suspend fun byId(id: String): AccuracyCheckEntity? + + @Query("SELECT * FROM accuracy_checks WHERE id = :id") + fun byIdFlow(id: String): Flow + + @Upsert + suspend fun upsert(check: AccuracyCheckEntity) + + @Query("SELECT * FROM accuracy_paused_units") + suspend fun allPausedUnits(): List + + @Query("SELECT * FROM accuracy_paused_units WHERE checkId = :checkId") + suspend fun pausedUnits(checkId: String): List + + @Query("SELECT * FROM accuracy_paused_units") + fun allPausedUnitsFlow(): Flow> + + /** Ignore: a unit already paused keeps its original [AccuracyPausedUnitEntity.pausedFrom]. */ + @Insert(onConflict = OnConflictStrategy.IGNORE) + suspend fun insertPausedUnits(units: List) + + @Query("SELECT * FROM accuracy_check_days WHERE checkId = :checkId") + suspend fun days(checkId: String): List + + @Query("SELECT * FROM accuracy_check_days WHERE checkId = :checkId") + fun daysFlow(checkId: String): Flow> + + @Query("SELECT * FROM accuracy_check_days") + suspend fun allDays(): List + + @Upsert + suspend fun upsertDays(days: List) + + @Query("DELETE FROM accuracy_check_days WHERE checkId = :checkId") + suspend fun clearDays(checkId: String) + + @Query("SELECT * FROM accuracy_corrections") + suspend fun allCorrections(): List + + @Query("SELECT * FROM accuracy_corrections") + fun allCorrectionsFlow(): Flow> + + @Query("SELECT * FROM accuracy_corrections WHERE deviceKey = :deviceKey") + suspend fun corrections(deviceKey: String): List + + @Upsert + suspend fun upsertCorrection(c: AccuracyCorrectionEntity) + + @Query("DELETE FROM accuracy_corrections WHERE deviceKey = :deviceKey AND metric = :metric") + suspend fun deleteCorrection(deviceKey: String, metric: String) +} diff --git a/app/src/main/java/com/pulseloop/data/entity/AccuracyEntities.kt b/app/src/main/java/com/pulseloop/data/entity/AccuracyEntities.kt new file mode 100644 index 00000000..1dc3be78 --- /dev/null +++ b/app/src/main/java/com/pulseloop/data/entity/AccuracyEntities.kt @@ -0,0 +1,122 @@ +package com.pulseloop.data.entity + +import androidx.room.Entity +import androidx.room.Index +import androidx.room.PrimaryKey + +/** + * One accuracy check: the ring compared against another device's Health Connect data for a few + * days (docs/accuracy-check-plan.md). At most one check is open (RUNNING or AWAITING_RESUME) at a + * time; [com.pulseloop.health.accuracy.AccuracyCheckController] owns every state change. + */ +@Entity(tableName = "accuracy_checks", indices = [Index("state")]) +data class AccuracyCheckEntity( + @PrimaryKey val id: String = java.util.UUID.randomUUID().toString(), + /** The ring this check belongs to ([com.pulseloop.health.accuracy.RingIdentity.keyOf]). */ + val deviceKey: String, + val deviceLabel: String, + val referencePackage: String, + /** What the user called the reference ("Health Sync (Huawei Watch GT 4)"). */ + val referenceLabel: String, + val startedAt: Long, + val plannedEndAt: Long, + val endedAt: Long? = null, + /** RUNNING → AWAITING_RESUME (ended, export choice pending) → DONE. */ + val state: String = STATE_RUNNING, + /** Why it ended: COMPLETED, ENDED_EARLY, RING_CHANGED. */ + val endReason: String? = null, + /** The export choice made on resume: SKIP (the default) or EXPORT. */ + val resumeChoice: String? = null, + /** User-edited agreement bands, `metric=value;…`; null = defaults. */ + val bandsRaw: String? = null, + /** Last time the pause set was re-read from the reference's Health Connect records. */ + val pauseRefreshedAt: Long? = null, + /** Last time the days were scored. */ + val scoredAt: Long? = null, + /** The ring's firmware when the check started, so a correction can tell it went stale. */ + val firmware: String? = null, +) { + val isOpen: Boolean get() = state == STATE_RUNNING || state == STATE_AWAITING_RESUME + + companion object { + const val STATE_RUNNING = "RUNNING" + const val STATE_AWAITING_RESUME = "AWAITING_RESUME" + const val STATE_DONE = "DONE" + + const val END_COMPLETED = "COMPLETED" + const val END_EARLY = "ENDED_EARLY" + const val END_RING_CHANGED = "RING_CHANGED" + + const val RESUME_SKIP = "SKIP" + const val RESUME_EXPORT = "EXPORT" + } +} + +/** + * One Health Connect export unit held back during a check, because the reference device writes + * the same type ([com.pulseloop.health.accuracy.ExportUnit]). [pausedFrom] is when holding back + * began: the check's start for types seen at start, later for a type the reference only started + * writing mid-check. + */ +@Entity(tableName = "accuracy_paused_units", primaryKeys = ["checkId", "unit"]) +data class AccuracyPausedUnitEntity( + val checkId: String, + val unit: String, + val pausedFrom: Long, +) + +/** + * One scored day of one metric in one check — aggregates only, never the reference's readings + * (plan, "Reading the reference data"). Paired metrics (heart rate, SpO₂) keep sums so days + * combine exactly; daily totals keep the two values. + */ +@Entity(tableName = "accuracy_check_days", primaryKeys = ["checkId", "metric", "day"]) +data class AccuracyCheckDayEntity( + val checkId: String, + /** [com.pulseloop.health.accuracy.ComparisonMetric] name. */ + val metric: String, + /** Epoch day (local). For sleep, the waking day. */ + val day: Long, + val ringValue: Double? = null, + val refValue: Double? = null, + /** Pairs compared (samples, or minutes for sleep stages); 1 for a daily total. */ + val pairs: Int = 0, + val sumDiff: Double = 0.0, + val sumSqDiff: Double = 0.0, + val sumAbsDiff: Double = 0.0, + /** Pairs inside the agreement band at scoring time (sleep stages: minutes on the same stage). */ + val inBand: Int = 0, + /** False for a day either device clearly wasn't worn, or the reference hasn't delivered yet. */ + val valid: Boolean = true, + /** Why a day doesn't count, or extra detail (stage confusion counts). */ + val note: String? = null, + val computedAt: Long = System.currentTimeMillis(), +) + +/** + * A correction fitted from a check, for one ring and one metric (plan, "Corrections"). Applied at + * read time only — stored rows stay exactly as the ring sent them, and nothing corrected reaches + * Health Connect. + */ +@Entity(tableName = "accuracy_corrections", primaryKeys = ["deviceKey", "metric"]) +data class AccuracyCorrectionEntity( + val deviceKey: String, + /** [com.pulseloop.health.accuracy.CorrectionMetric] name. */ + val metric: String, + /** SCALE (multiply) or OFFSET (add). */ + val kind: String, + /** The value in use — the fitted one, or what the user moved the slider to. */ + val value: Double, + val fittedValue: Double, + val fromCheckId: String, + val enabled: Boolean = true, + /** The ring's firmware when fitted; a different firmware makes the correction stale. */ + val firmware: String? = null, + val createdAt: Long = System.currentTimeMillis(), + val updatedAt: Long = System.currentTimeMillis(), +) { + companion object { + const val KIND_SCALE = "SCALE" + const val KIND_OFFSET = "OFFSET" + } +} diff --git a/app/src/main/java/com/pulseloop/data/entity/CoreEntities.kt b/app/src/main/java/com/pulseloop/data/entity/CoreEntities.kt index 0720dfbe..a52c6b2b 100644 --- a/app/src/main/java/com/pulseloop/data/entity/CoreEntities.kt +++ b/app/src/main/java/com/pulseloop/data/entity/CoreEntities.kt @@ -87,6 +87,12 @@ data class ActivityDailyEntity( /** Ported from iOS #98: net active calories estimated from all-day HR + step buckets when the * ring does not report device-side calories. Read through [effectiveActiveCalories]. */ val estimatedActiveCalories: Double? = null, + /** + * [estimatedActiveCalories] recomputed with the ring's accuracy corrections applied to its + * inputs (docs/accuracy-check-plan.md, Corrections rule 6), or null when no correction applies. + * The app shows this one; Health Connect gets the raw one, never this. + */ + val estimatedActiveCaloriesAdjusted: Double? = null, /** * What this day's deleted activity buckets contributed, kept so the ring's own cumulative * counter can be corrected for them (issue #70). diff --git a/app/src/main/java/com/pulseloop/health/HealthConnectExporter.kt b/app/src/main/java/com/pulseloop/health/HealthConnectExporter.kt index 86731814..7654b986 100644 --- a/app/src/main/java/com/pulseloop/health/HealthConnectExporter.kt +++ b/app/src/main/java/com/pulseloop/health/HealthConnectExporter.kt @@ -8,6 +8,7 @@ import androidx.health.connect.client.records.ExerciseSessionRecord import androidx.health.connect.client.records.Record import androidx.health.connect.client.records.metadata.Device import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.health.accuracy.ExportPause import com.pulseloop.health.exporters.ActivityExporter import com.pulseloop.health.exporters.NutritionExporter import com.pulseloop.health.exporters.RestingHeartRateExporter @@ -300,6 +301,16 @@ class HealthConnectExporter( val skipped = mutableListOf() val errors = mutableListOf() + // Accuracy check (docs/accuracy-check-plan.md): records of a type the reference device also + // writes are held back for the check's window — by data time, so the watermarks below still + // advance past them (see [ExportPause]). Read once per pass; the pass runs under + // HealthConnectExportWorker.passMutex, which the resume choice also takes, so a choice can't + // land halfway through a pass. + val exclusions = ExportPause.exclusions(db.accuracyDao().all(), db.accuracyDao().allPausedUnits()) + fun noteHeldBack(label: String, f: ExportPause.Filtered) { + if (f.heldBack > 0) skipped += "$label: ${f.heldBack} record(s) held back by the accuracy check" + } + // ── Vitals group (Phase 1; watermarked on Measurement.createdAt, one group watermark) ── val kindToggles = mapOf( "hr" to prefs.heartRate, @@ -336,7 +347,13 @@ class HealthConnectExporter( skipped += kindLabels.getValue(kindKey) + " (permission not granted)" continue } - val pending = exporter.build(kindKey, effectiveWatermark(vitalsWm, prefs.newOnlyConsentAt), device) + val built = exporter.build(kindKey, effectiveWatermark(vitalsWm, prefs.newOnlyConsentAt), device) + val held = ExportPause.filter(built.records, built.highWaters, exclusions) + noteHeldBack(kindLabels.getValue(kindKey), held) + val pending = built.copy( + records = held.records, highWaters = held.highWaters, + droppedHighWater = ExportPause.maxOfNullable(built.droppedHighWater, held.heldBackHighWater), + ) val progress = insertChunked(pending.records, pending.highWaters) { chunk -> client.insertRecords(chunk) } @@ -378,7 +395,13 @@ class HealthConnectExporter( if (permission !in granted) { skipped += "sleep (permission not granted)" } else { - val sleepPending = SleepExporter(db).build(effectiveWatermark(wm0.sleep, prefs.newOnlyConsentAt), device) + val sleepBuilt = SleepExporter(db).build(effectiveWatermark(wm0.sleep, prefs.newOnlyConsentAt), device) + val sleepHeld = ExportPause.filter(sleepBuilt.records, sleepBuilt.highWaters, exclusions) + noteHeldBack("sleep", sleepHeld) + val sleepPending = sleepBuilt.copy( + records = sleepHeld.records, highWaters = sleepHeld.highWaters, + droppedHighWater = ExportPause.maxOfNullable(sleepBuilt.droppedHighWater, sleepHeld.heldBackHighWater), + ) val sleepProgress = insertChunked(sleepPending.records, sleepPending.highWaters) { chunk -> client.insertRecords(chunk) } @@ -434,7 +457,7 @@ class HealthConnectExporter( } val metrics = metricPermissions.filterValues { it in granted }.keys if (metrics.isNotEmpty()) { - val activityPending = ActivityExporter(db).build( + val activityBuilt = ActivityExporter(db).build( watermark = effectiveWatermark(wm0.activity, prefs.newOnlyConsentAt), device = device, metrics = metrics, @@ -443,6 +466,12 @@ class HealthConnectExporter( netWorkouts = shouldNetWorkouts(prefs, granted), nowMs = timestamp, ) + val activityHeld = ExportPause.filter(activityBuilt.records, activityBuilt.highWaters, exclusions) + noteHeldBack("activity", activityHeld) + val activityPending = activityBuilt.copy( + records = activityHeld.records, highWaters = activityHeld.highWaters, + droppedHighWater = ExportPause.maxOfNullable(activityBuilt.droppedHighWater, activityHeld.heldBackHighWater), + ) val activityProgress = insertChunked(activityPending.records, activityPending.highWaters) { chunk -> client.insertRecords(chunk) } @@ -492,9 +521,16 @@ class HealthConnectExporter( val withRoute = HealthConnectPermissions.exerciseRoute.first() in granted val withEnergy = HealthConnectPermissions.activeCalories.first() in granted val withDistance = HealthConnectPermissions.distance.first() in granted - val workoutsPending = WorkoutExporter(db).build( + val workoutsBuilt = WorkoutExporter(db).build( effectiveWatermark(wm0.workouts, prefs.newOnlyConsentAt), device, withRoute, withEnergy, withDistance, timestamp, ) + // Only the calorie and distance siblings can be held back; the session always exports. + val workoutsHeld = ExportPause.filter(workoutsBuilt.records, workoutsBuilt.highWaters, exclusions) + noteHeldBack("workouts", workoutsHeld) + val workoutsPending = workoutsBuilt.copy( + records = workoutsHeld.records, highWaters = workoutsHeld.highWaters, + invalidHighWater = ExportPause.maxOfNullable(workoutsBuilt.invalidHighWater, workoutsHeld.heldBackHighWater), + ) val workoutsProgress = insertChunked(workoutsPending.records, workoutsPending.highWaters) { chunk -> insertChunkWithRouteShrink(chunk) { client.insertRecords(it) } } @@ -546,7 +582,12 @@ class HealthConnectExporter( if (restingPermission !in granted) { skipped += "resting heart rate (permission not granted)" } else { - val restingPending = RestingHeartRateExporter(db).build(effectiveWatermark(wm0.restingHr, prefs.newOnlyConsentAt), device) + val restingBuilt = RestingHeartRateExporter(db).build(effectiveWatermark(wm0.restingHr, prefs.newOnlyConsentAt), device) + val restingHeld = ExportPause.filter(restingBuilt.records, restingBuilt.highWaters, exclusions) + noteHeldBack("resting heart rate", restingHeld) + // Empty after holding back takes the "nothing to export" branch below, which moves + // the watermark to now — past the held-back baseline, as for every other group. + val restingPending = restingBuilt.copy(records = restingHeld.records, highWaters = restingHeld.highWaters) if (restingPending.records.isEmpty()) { // Nothing to export (no baseline yet, already current, or implausible): the // group's "everything exported" point is now - same rule as the other groups. diff --git a/app/src/main/java/com/pulseloop/health/HealthConnectPrefsStore.kt b/app/src/main/java/com/pulseloop/health/HealthConnectPrefsStore.kt index 3473d15f..eda62dda 100644 --- a/app/src/main/java/com/pulseloop/health/HealthConnectPrefsStore.kt +++ b/app/src/main/java/com/pulseloop/health/HealthConnectPrefsStore.kt @@ -304,6 +304,30 @@ class HealthConnectPrefsStore internal constructor(private val prefsStore: Share } } + /** + * Move the named groups' watermarks back to [to], never forward — the accuracy check's + * "Export them too" (docs/accuracy-check-plan.md): rows written since the check began + * re-select and export now that their exclusion is gone, and nothing older is re-read. A null + * watermark stays null (that group never exported, so it will reach the window anyway), and + * an EXPORT_NEW_ONLY user is never rewound past the consent instant. + */ + fun rewindWatermarks(keys: Set, to: Long) { + if (keys.isEmpty()) return + synchronized(writeLock) { + val prefs = _prefs.value + val floor = if (prefs.backfillChoice == HealthConnectPrefs.BackfillChoice.EXPORT_NEW_ONLY) { + maxOf(to, prefs.newOnlyConsentAt ?: to) + } else to + var next = _watermarks.value + for (key in keys) { + val cur = next.get(key) ?: continue + if (floor < cur) next = next.copyWith(key, floor) + } + if (next == _watermarks.value) return + _watermarks.value = next + prefsStore.edit().putString(KEY_WATERMARKS, json.encodeToString(HealthConnectWatermarks.serializer(), next)).apply() + } + } /** Clear every watermark (iOS `removeAllExportedData`; Phase 6 revocation reset). */ fun clearWatermarks() { diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckController.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckController.kt new file mode 100644 index 00000000..e1f3b7b2 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckController.kt @@ -0,0 +1,206 @@ +package com.pulseloop.health.accuracy + +import android.content.Context +import android.util.Log +import androidx.health.connect.client.HealthConnectClient +import androidx.health.connect.client.records.Record +import androidx.health.connect.client.records.metadata.DataOrigin +import androidx.health.connect.client.request.ReadRecordsRequest +import androidx.health.connect.client.time.TimeRangeFilter +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.data.entity.AccuracyPausedUnitEntity +import com.pulseloop.data.entity.DeviceEntity +import com.pulseloop.health.HealthConnectAvailability +import com.pulseloop.health.HealthConnectExportWorker +import com.pulseloop.health.HealthConnectPrefsStore +import com.pulseloop.health.HealthConnectSdk +import kotlinx.coroutines.sync.withLock +import java.time.Instant +import kotlin.reflect.KClass + +/** Which ring a check or a correction belongs to. */ +object RingIdentity { + const val DEMO_DEVICE_ID = "demo-device" + + /** + * The BLE address when known: the device row is reused across pairings, so its id doesn't + * change when the user switches rings, but the address does. + */ + fun keyOf(d: DeviceEntity): String = + (d.bleAddressHint ?: d.peripheralIdentifier ?: d.id).uppercase() + + fun labelOf(d: DeviceEntity): String = + (d.advertisedName?.takeIf { it.isNotBlank() } ?: d.name).ifBlank { "Ring" } +} + +/** + * Every state change of an accuracy check goes through here (docs/accuracy-check-plan.md, + * Phase 1): start, the pause set growing, ending (on time, early, or because a different ring + * connected), and the resume choice that decides what happens to the check window's held-back + * Health Connect export. + */ +object AccuracyCheckController { + + private const val TAG = "AccuracyCheck" + val DURATIONS_DAYS = listOf(3, 5, 7, 14) + const val DEFAULT_DAYS = 7 + private const val DAY_MS = 86_400_000L + + sealed interface StartResult { + data class Started(val check: AccuracyCheckEntity) : StartResult + data object AlreadyOpen : StartResult + data object NoRing : StartResult + data object NothingToCompare : StartResult + } + + suspend fun start( + context: Context, + source: ReferenceSourceSurvey, + referenceLabel: String, + days: Int, + now: Long = System.currentTimeMillis(), + ): StartResult { + val db = PulseLoopDatabase.getInstance(context) + val dao = db.accuracyDao() + if (dao.open() != null) return StartResult.AlreadyOpen + val ring = db.deviceDao().currentReal() ?: return StartResult.NoRing + val units = source.metrics.map { ExportUnit.of(it.metric) }.toSet() + if (units.isEmpty()) return StartResult.NothingToCompare + val check = AccuracyCheckEntity( + deviceKey = RingIdentity.keyOf(ring), + deviceLabel = RingIdentity.labelOf(ring), + referencePackage = source.packageName, + referenceLabel = referenceLabel.ifBlank { source.packageName }, + startedAt = now, + plannedEndAt = now + days.coerceAtLeast(DURATIONS_DAYS.first()) * DAY_MS, + pauseRefreshedAt = now, + firmware = ring.firmwareVersion, + ) + dao.upsert(check) + dao.insertPausedUnits(units.map { AccuracyPausedUnitEntity(check.id, it.name, pausedFrom = now) }) + AccuracyCheckWorker.schedule(context, check.plannedEndAt) + Log.i(TAG, "started ${check.id}: ${check.referencePackage}, ${units.joinToString()} paused until ${Instant.ofEpochMilli(check.plannedEndAt)}") + return StartResult.Started(check) + } + + /** RUNNING → AWAITING_RESUME. Export stays paused until [resolve]. */ + suspend fun end(context: Context, reason: String, at: Long = System.currentTimeMillis()): AccuracyCheckEntity? { + val dao = PulseLoopDatabase.getInstance(context).accuracyDao() + val check = dao.open()?.takeIf { it.state == AccuracyCheckEntity.STATE_RUNNING } ?: return null + val ended = check.copy( + state = AccuracyCheckEntity.STATE_AWAITING_RESUME, + endedAt = at.coerceIn(check.startedAt, check.plannedEndAt), + endReason = reason, + ) + dao.upsert(ended) + AccuracyCheckWorker.cancelEnd(context) + Log.i(TAG, "ended ${check.id}: $reason") + return ended + } + + /** + * AWAITING_RESUME → DONE. [AccuracyCheckEntity.RESUME_SKIP] closes the exclusions at the check's + * end, and that is all it needs to do: the export already advanced past the held-back records. + * [AccuracyCheckEntity.RESUME_EXPORT] drops the exclusions and rewinds each affected watermark to + * where holding back began, so the window's rows re-select. Taken under the export's pass + * mutex: a pass in flight could otherwise advance a watermark past the rewind. + */ + suspend fun resolve(context: Context, choice: String) { + val db = PulseLoopDatabase.getInstance(context) + val dao = db.accuracyDao() + val check = dao.open()?.takeIf { it.state == AccuracyCheckEntity.STATE_AWAITING_RESUME } ?: return + HealthConnectExportWorker.passMutex.withLock { + dao.upsert(check.copy(state = AccuracyCheckEntity.STATE_DONE, resumeChoice = choice)) + if (choice == AccuracyCheckEntity.RESUME_EXPORT) { + val store = HealthConnectPrefsStore.get(context) + dao.pausedUnits(check.id) + .mapNotNull { p -> ExportUnit.byName(p.unit)?.let { it.watermark to p.pausedFrom } } + .groupBy({ it.first }, { it.second }) + .forEach { (key, froms) -> store.rewindWatermarks(setOf(key), froms.min()) } + } + } + AccuracyCheckWorker.cancelAll(context) + HealthConnectExportWorker.enqueue(context) + } + + /** Ends a running check whose time is up. Returns the check it ended, if any. */ + suspend fun endIfDue(context: Context, now: Long = System.currentTimeMillis()): AccuracyCheckEntity? { + val check = PulseLoopDatabase.getInstance(context).accuracyDao().open() ?: return null + if (check.state != AccuracyCheckEntity.STATE_RUNNING || now < check.plannedEndAt) return null + return end(context, AccuracyCheckEntity.END_COMPLETED, check.plannedEndAt) + } + + /** + * A different ring is now the paired one: data from here on isn't this check's ring, so the + * check ends now (plan, "Changing rings"). The export pause follows the reference device and + * stays until the resume choice. + */ + suspend fun onRingChanged(context: Context, device: DeviceEntity, now: Long = System.currentTimeMillis()) { + val check = PulseLoopDatabase.getInstance(context).accuracyDao().open() ?: return + if (check.state != AccuracyCheckEntity.STATE_RUNNING) return + val key = RingIdentity.keyOf(device) + if (key == check.deviceKey) return + // Same row, better key: the check started before the address was known and was keyed on + // the row id or peripheral id. That's the same ring learning its address, not a new ring. + val weakerKeys = listOfNotNull(device.id, device.peripheralIdentifier).map { it.uppercase() } + if (check.deviceKey in weakerKeys) { + PulseLoopDatabase.getInstance(context).accuracyDao().upsert(check.copy(deviceKey = key)) + return + } + end(context, AccuracyCheckEntity.END_RING_CHANGED, now) + } + + /** + * Grows the pause set with any type the reference started writing since the check began + * (plan: the set comes from the reference device, never from the ring). Each joins from the + * time of the reference's first record of it, not from the start of the check. Needs a + * Health Connect read, so it runs in the foreground; background reads may be refused. + */ + suspend fun refreshPauseSet(context: Context, now: Long = System.currentTimeMillis()): Set { + val db = PulseLoopDatabase.getInstance(context) + val dao = db.accuracyDao() + val check = dao.open()?.takeIf { it.state == AccuracyCheckEntity.STATE_RUNNING } ?: return emptySet() + if (HealthConnectSdk.availability(context) != HealthConnectAvailability.AVAILABLE) return emptySet() + val client = HealthConnectClient.getOrCreate(context) + val readable = AccuracyCheckPermissions.readable(ReferenceSourceScanner.grantedPermissions(context)) + val already = dao.pausedUnits(check.id).mapNotNull { ExportUnit.byName(it.unit) }.toSet() + val added = mutableSetOf() + for (unit in ExportUnit.entries) { + if (unit in already || unit.metric !in readable) continue + val first = runCatching { + firstRecordTime(client, unit.metric.recordType, check.referencePackage, check.startedAt, now) + }.onFailure { Log.w(TAG, "pause refresh ${unit.name} failed", it) }.getOrNull() ?: continue + dao.insertPausedUnits(listOf(AccuracyPausedUnitEntity(check.id, unit.name, pausedFrom = maxOf(check.startedAt, first)))) + added += unit + } + dao.upsert(check.copy(pauseRefreshedAt = now)) + if (added.isNotEmpty()) Log.i(TAG, "pause set grew: ${added.joinToString()}") + return added + } + + private suspend fun firstRecordTime( + client: HealthConnectClient, + type: KClass, + pkg: String, + from: Long, + to: Long, + ): Long? { + val r = client.readRecords( + ReadRecordsRequest( + type, + TimeRangeFilter.between(Instant.ofEpochMilli(from), Instant.ofEpochMilli(to)), + dataOriginFilter = setOf(DataOrigin(pkg)), + ascendingOrder = true, + pageSize = 1, + ), + ).records.firstOrNull() ?: return null + return ReferenceRecords.startOf(r) + } + + /** Units the open check holds back right now, for the export settings screen. */ + suspend fun pausedNow(context: Context): Set { + val dao = PulseLoopDatabase.getInstance(context).accuracyDao() + return ExportPause.pausedNow(ExportPause.exclusions(dao.all(), dao.allPausedUnits())) + } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckPermissions.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckPermissions.kt index 94afa7d7..bc1140e3 100644 --- a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckPermissions.kt +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckPermissions.kt @@ -41,6 +41,13 @@ object AccuracyCheckPermissions { val all: Set = ReferenceMetric.entries.map(::readPermission).toSet() + /** + * What the screen asks for: the types, plus background reading so the 6-hourly worker can + * grow the pause set without the app open. Optional — where Health Connect doesn't offer it, + * or the user declines, the pause set is refreshed whenever the screen is opened instead. + */ + val request: Set = all + HealthPermission.PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND + /** The metrics [granted] lets the scan read. */ fun readable(granted: Set): Set = ReferenceMetric.entries.filter { readPermission(it) in granted }.toSet() diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckWorker.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckWorker.kt new file mode 100644 index 00000000..5aa29985 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCheckWorker.kt @@ -0,0 +1,119 @@ +package com.pulseloop.health.accuracy + +import android.Manifest +import android.app.NotificationChannel +import android.app.NotificationManager +import android.app.PendingIntent +import android.content.Context +import android.content.Intent +import android.content.pm.PackageManager +import android.os.Build +import android.util.Log +import androidx.core.app.NotificationCompat +import androidx.core.app.NotificationManagerCompat +import androidx.core.content.ContextCompat +import androidx.health.connect.client.records.Record +import androidx.work.CoroutineWorker +import androidx.work.ExistingPeriodicWorkPolicy +import androidx.work.ExistingWorkPolicy +import androidx.work.OneTimeWorkRequestBuilder +import androidx.work.PeriodicWorkRequestBuilder +import androidx.work.WorkManager +import androidx.work.WorkerParameters +import com.pulseloop.MainActivity +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckEntity +import java.util.concurrent.TimeUnit + +/** Record time accessors shared by the controller and the comparison reader. */ +internal object ReferenceRecords { + fun startOf(r: Record): Long? = ExportPause.span(r)?.first +} + +/** + * Ends a check on time even if the app is never opened, and tells the user the report is ready. + * A one-shot at the planned end, backed by a 6-hourly periodic run (WorkManager can defer the + * one-shot under Doze). It also tries the pause-set refresh; a Health Connect read from the + * background may be refused, in which case the next foreground open does it. + */ +class AccuracyCheckWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) { + + override suspend fun doWork(): Result { + val open = PulseLoopDatabase.getInstance(applicationContext).accuracyDao().open() + if (open == null) { + cancelAll(applicationContext) + return Result.success() + } + AccuracyCheckController.endIfDue(applicationContext)?.let { AccuracyNotifications.reportReady(applicationContext, it) } + runCatching { AccuracyCheckController.refreshPauseSet(applicationContext) } + .onFailure { Log.i(TAG, "background pause refresh not possible: ${it.message}") } + return Result.success() + } + + companion object { + private const val TAG = "AccuracyCheckWorker" + private const val PERIODIC = "accuracy_check" + private const val END = "accuracy_check_end" + + fun schedule(context: Context, plannedEndAt: Long, now: Long = System.currentTimeMillis()) { + val wm = WorkManager.getInstance(context.applicationContext) + wm.enqueueUniquePeriodicWork( + PERIODIC, ExistingPeriodicWorkPolicy.KEEP, + PeriodicWorkRequestBuilder(6, TimeUnit.HOURS).build(), + ) + wm.enqueueUniqueWork( + END, ExistingWorkPolicy.REPLACE, + OneTimeWorkRequestBuilder() + .setInitialDelay((plannedEndAt - now).coerceAtLeast(0), TimeUnit.MILLISECONDS) + .build(), + ) + } + + fun cancelEnd(context: Context) { + WorkManager.getInstance(context.applicationContext).cancelUniqueWork(END) + } + + fun cancelAll(context: Context) { + val wm = WorkManager.getInstance(context.applicationContext) + wm.cancelUniqueWork(END) + wm.cancelUniqueWork(PERIODIC) + } + } +} + +object AccuracyNotifications { + private const val CHANNEL_ID = "accuracy_check" + private const val NOTIFICATION_ID = 2101 + + fun createChannel(context: Context) { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { + val channel = NotificationChannel(CHANNEL_ID, "Accuracy check", NotificationManager.IMPORTANCE_DEFAULT).apply { + description = "When an accuracy check against another device has finished" + } + (context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager).createNotificationChannel(channel) + } + } + + fun reportReady(context: Context, check: AccuracyCheckEntity) { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && + ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED + ) return + createChannel(context) + val intent = Intent(context, MainActivity::class.java).apply { + flags = Intent.FLAG_ACTIVITY_NEW_TASK + action = MainActivity.ACTION_OPEN_ACCURACY_CHECK + } + val pending = PendingIntent.getActivity(context, NOTIFICATION_ID, intent, PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT) + val notification = NotificationCompat.Builder(context, CHANNEL_ID) + .setContentTitle("Your accuracy report is ready") + .setContentText("Your ring vs ${check.referenceLabel}. Health Connect export stays paused until you choose what to do with these days.") + .setStyle(NotificationCompat.BigTextStyle().bigText( + "Your ring vs ${check.referenceLabel}. Health Connect export stays paused until you choose what to do with these days.", + )) + .setSmallIcon(android.R.drawable.ic_dialog_info) + .setAutoCancel(true) + .setContentIntent(pending) + .build() + NotificationManagerCompat.from(context).notify(NOTIFICATION_ID, notification) + } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyRingWatcher.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyRingWatcher.kt new file mode 100644 index 00000000..77b8acb1 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyRingWatcher.kt @@ -0,0 +1,30 @@ +package com.pulseloop.health.accuracy + +import android.content.Context +import com.pulseloop.data.PulseLoopDatabase +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.flow.distinctUntilChanged +import kotlinx.coroutines.flow.filterNotNull +import kotlinx.coroutines.flow.map +import kotlinx.coroutines.launch + +/** + * Ends a running check the moment a different ring becomes the paired one (plan, "Changing + * rings"). Process-scoped, started from `PulseLoopApplication`: ring data carries no device id, so + * the switch has to be caught as it happens — a periodic check would score the new ring's first + * hours as the old ring's. + */ +object AccuracyRingWatcher { + fun start(context: Context, scope: CoroutineScope) { + val app = context.applicationContext + val db = PulseLoopDatabase.getInstance(app) + scope.launch { + db.deviceDao().currentFlow() + .filterNotNull() + .map { it.takeIf { d -> d.id != RingIdentity.DEMO_DEVICE_ID } } + .filterNotNull() + .distinctUntilChanged { a, b -> RingIdentity.keyOf(a) == RingIdentity.keyOf(b) } + .collect { runCatching { AccuracyCheckController.onRingChanged(app, it) } } + } + } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/ExportPause.kt b/app/src/main/java/com/pulseloop/health/accuracy/ExportPause.kt new file mode 100644 index 00000000..7017b67c --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/ExportPause.kt @@ -0,0 +1,165 @@ +package com.pulseloop.health.accuracy + +import androidx.health.connect.client.records.ActiveCaloriesBurnedRecord +import androidx.health.connect.client.records.DistanceRecord +import androidx.health.connect.client.records.HeartRateRecord +import androidx.health.connect.client.records.HeartRateVariabilityRmssdRecord +import androidx.health.connect.client.records.OxygenSaturationRecord +import androidx.health.connect.client.records.Record +import androidx.health.connect.client.records.RestingHeartRateRecord +import androidx.health.connect.client.records.SleepSessionRecord +import androidx.health.connect.client.records.StepsRecord +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.data.entity.AccuracyPausedUnitEntity +import com.pulseloop.health.HealthConnectPermissions +import com.pulseloop.health.HealthConnectWatermarks + +/** + * One kind of record PulseLoop exports that a reference device can also write — the granularity + * the accuracy check pauses at (plan, "Export pause and resume"). Finer than the export's settings + * rows: steps, distance and active calories are one row there but separate here, because a + * reference that writes steps and not calories should only hold back steps. + */ +enum class ExportUnit( + val metric: ReferenceMetric, + val row: HealthConnectPermissions.DataTypeRow, + val watermark: HealthConnectWatermarks.Key, +) { + HEART_RATE(ReferenceMetric.HEART_RATE, HealthConnectPermissions.DataTypeRow.HEART_RATE, HealthConnectWatermarks.Key.VITALS), + OXYGEN_SATURATION(ReferenceMetric.OXYGEN_SATURATION, HealthConnectPermissions.DataTypeRow.OXYGEN_SATURATION, HealthConnectWatermarks.Key.VITALS), + HRV(ReferenceMetric.HRV, HealthConnectPermissions.DataTypeRow.HEART_RATE_VARIABILITY, HealthConnectWatermarks.Key.VITALS), + SLEEP(ReferenceMetric.SLEEP, HealthConnectPermissions.DataTypeRow.SLEEP, HealthConnectWatermarks.Key.SLEEP), + STEPS(ReferenceMetric.STEPS, HealthConnectPermissions.DataTypeRow.STEPS_AND_ACTIVITY, HealthConnectWatermarks.Key.ACTIVITY), + DISTANCE(ReferenceMetric.DISTANCE, HealthConnectPermissions.DataTypeRow.STEPS_AND_ACTIVITY, HealthConnectWatermarks.Key.ACTIVITY), + ACTIVE_CALORIES(ReferenceMetric.ACTIVE_CALORIES, HealthConnectPermissions.DataTypeRow.STEPS_AND_ACTIVITY, HealthConnectWatermarks.Key.ACTIVITY), + RESTING_HEART_RATE(ReferenceMetric.RESTING_HEART_RATE, HealthConnectPermissions.DataTypeRow.RESTING_HEART_RATE, HealthConnectWatermarks.Key.RESTING_HR), + ; + + companion object { + fun of(metric: ReferenceMetric): ExportUnit = entries.first { it.metric == metric } + fun byName(name: String): ExportUnit? = entries.firstOrNull { it.name == name } + + /** + * The unit a record PulseLoop is about to export belongs to, by record type — so a + * workout's calorie and distance siblings are held back with the daily ones, which is + * right: the reference device writes those too. The workout session itself has no unit + * and always exports. + */ + fun ofRecord(r: Record): ExportUnit? = when (r) { + is HeartRateRecord -> HEART_RATE + is OxygenSaturationRecord -> OXYGEN_SATURATION + is HeartRateVariabilityRmssdRecord -> HRV + is SleepSessionRecord -> SLEEP + is StepsRecord -> STEPS + is DistanceRecord -> DISTANCE + is ActiveCaloriesBurnedRecord -> ACTIVE_CALORIES + is RestingHeartRateRecord -> RESTING_HEART_RATE + else -> null + } + } +} + +/** Records of [unit] whose data time overlaps `[from, until)` are not exported. Open while [until] is null. */ +data class ExportExclusion(val unit: ExportUnit, val from: Long, val until: Long?) { + fun overlaps(start: Long, end: Long): Boolean = end >= from && (until == null || start < until) +} + +/** + * The export side of the accuracy check: which records to hold back, and how the exporter skips + * them without stalling its watermarks. Pure apart from the record-time accessors. + * + * **Filtered by data time, not by watermark.** A paused record is dropped from the pass and its + * watermark still advances past it, exactly like a never-exportable row. That is what makes + * "skip the check window" the default with nothing to do on resume, and what keeps it skipped: + * a record from the window that is updated later (a re-synced night, a day whose total grows) + * re-selects, meets the same closed exclusion, and is dropped again. "Export them too" removes + * the exclusion and rewinds the affected watermarks to the window's start instead. + * + * A record is held back when its interval *overlaps* the window, so a whole-day activity record + * for the day a check starts or ends is held back too: its total includes steps from inside the + * window, which the reference device also wrote. + */ +object ExportPause { + + /** + * Exclusions in force: open for a check that is running or waiting for the resume choice, + * closed at its end for a check resolved with SKIP, none for one resolved with EXPORT. + */ + fun exclusions(checks: List, paused: List): List { + val byCheck = paused.groupBy { it.checkId } + return checks.flatMap { c -> + val until: Long? = when { + c.isOpen -> null + c.state == AccuracyCheckEntity.STATE_DONE && c.resumeChoice == AccuracyCheckEntity.RESUME_SKIP -> c.endedAt ?: return@flatMap emptyList() + else -> return@flatMap emptyList() + } + byCheck[c.id].orEmpty().mapNotNull { p -> + val unit = ExportUnit.byName(p.unit) ?: return@mapNotNull null + // A unit that joined the pause set after the check ended (can't happen through the + // controller) would make an inverted window; drop it rather than exclude nothing oddly. + if (until != null && until <= p.pausedFrom) null else ExportExclusion(unit, p.pausedFrom, until) + } + } + } + + /** Units currently held back (an open window). */ + fun pausedNow(exclusions: List): Set = + exclusions.filter { it.until == null }.map { it.unit }.toSet() + + data class Filtered( + val records: List, + val highWaters: List, + /** Max high water among the held-back records, for the watermark advance; null if none. */ + val heldBackHighWater: Long?, + val heldBack: Int, + ) + + fun filter(records: List, highWaters: List, exclusions: List): Filtered { + require(records.size == highWaters.size) { "records/highWaters must be parallel" } + if (exclusions.isEmpty()) return Filtered(records, highWaters, null, 0) + val keptR = ArrayList(records.size) + val keptH = ArrayList(records.size) + var heldHigh: Long? = null + var held = 0 + for (i in records.indices) { + val r = records[i] + if (isHeldBack(r, exclusions)) { + held++ + heldHigh = maxOf(heldHigh ?: Long.MIN_VALUE, highWaters[i]) + } else { + keptR += r + keptH += highWaters[i] + } + } + return Filtered(keptR, keptH, heldHigh, held) + } + + fun isHeldBack(r: Record, exclusions: List): Boolean { + val unit = ExportUnit.ofRecord(r) ?: return false + val (start, end) = span(r) ?: return false + return exclusions.any { it.unit == unit && it.overlaps(start, end) } + } + + /** + * A record's data time, start to end. Spelled out per type because the library keeps its + * `InstantaneousRecord` / `IntervalRecord` interfaces internal. + */ + fun span(r: Record): Pair? = when (r) { + is HeartRateRecord -> r.startTime.toEpochMilli() to r.endTime.toEpochMilli() + is SleepSessionRecord -> r.startTime.toEpochMilli() to r.endTime.toEpochMilli() + is StepsRecord -> r.startTime.toEpochMilli() to r.endTime.toEpochMilli() + is DistanceRecord -> r.startTime.toEpochMilli() to r.endTime.toEpochMilli() + is ActiveCaloriesBurnedRecord -> r.startTime.toEpochMilli() to r.endTime.toEpochMilli() + is OxygenSaturationRecord -> r.time.toEpochMilli().let { it to it } + is HeartRateVariabilityRmssdRecord -> r.time.toEpochMilli().let { it to it } + is RestingHeartRateRecord -> r.time.toEpochMilli().let { it to it } + else -> null + } + + /** Max of two nullable high waters — how a held-back high water joins an exporter's dropped one. */ + fun maxOfNullable(a: Long?, b: Long?): Long? = when { + a == null -> b + b == null -> a + else -> maxOf(a, b) + } +} diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt index eb6b4a70..e7ee4e7b 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt @@ -5,6 +5,17 @@ import android.content.ClipboardManager import android.content.Context import androidx.activity.compose.rememberLauncherForActivityResult import androidx.compose.foundation.background +import androidx.compose.foundation.clickable +import androidx.compose.material3.AlertDialog +import androidx.compose.material3.FilterChip +import androidx.compose.material3.OutlinedTextField +import androidx.compose.material3.TextButton +import androidx.compose.runtime.collectAsState +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.health.accuracy.AccuracyCheckController +import com.pulseloop.health.accuracy.ExportUnit +import com.pulseloop.health.accuracy.RingIdentity import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.Row @@ -47,20 +58,26 @@ import java.time.ZoneId import java.time.format.DateTimeFormatter /** - * Settings → Accuracy check, Phase 0 (docs/accuracy-check-plan.md): grant read access, then scan - * Health Connect for which apps write what, how often and how late. Starting a check comes in a - * later phase; this screen is useful on its own, and it answers the questions the later phases - * depend on (does Health Sync name the device, how sparse is its heart rate, how far behind is it). + * Settings → Accuracy check (docs/accuracy-check-plan.md). With no check open: grant read access, + * scan Health Connect for which apps write what, how often and how late, and start a check + * against one of them. With one open: its progress or the resume choice, and the report. */ @Composable fun AccuracyCheckSettingsScreen(onBack: () -> Unit) { val context = LocalContext.current val scope = rememberCoroutineScope() + val db = remember { PulseLoopDatabase.getInstance(context) } val available = remember { HealthConnectSdk.availability(context) == HealthConnectAvailability.AVAILABLE } var granted by remember { mutableStateOf>(emptySet()) } var scanning by remember { mutableStateOf(false) } var result by remember { mutableStateOf(null) } var note by remember { mutableStateOf(null) } + var starting by remember { mutableStateOf(null) } + var viewing by remember { mutableStateOf(null) } + val open by db.accuracyDao().openFlow().collectAsState(initial = null) + val history by db.accuracyDao().allFlow().collectAsState(initial = emptyList()) + val ring by db.deviceDao().currentFlow().collectAsState(initial = null) + val hasRing = ring?.let { it.id != RingIdentity.DEMO_DEVICE_ID } == true fun scan() { scanning = true @@ -75,7 +92,13 @@ fun AccuracyCheckSettingsScreen(onBack: () -> Unit) { } } - LaunchedEffect(Unit) { granted = ReferenceSourceScanner.grantedPermissions(context) } + LaunchedEffect(Unit) { + granted = ReferenceSourceScanner.grantedPermissions(context) + // Foreground is where Health Connect reads are reliable: end a check whose time is up, and + // pick up any type the reference started writing. + runCatching { AccuracyCheckController.endIfDue(context) } + runCatching { AccuracyCheckController.refreshPauseSet(context) } + } val readable = AccuracyCheckPermissions.readable(granted) val launcher = rememberLauncherForActivityResult(PermissionController.createRequestPermissionResultContract()) { got -> @@ -85,70 +108,257 @@ fun AccuracyCheckSettingsScreen(onBack: () -> Unit) { } else scan() } + val viewingCheck = viewing?.let { id -> history.firstOrNull { it.id == id } } + if (viewingCheck != null) { + SettingsSubScreen(title = "Accuracy report", onBack = { viewing = null }) { + AccuracyReportSection(viewingCheck) + } + return + } + SettingsSubScreen(title = "Accuracy check", onBack = onBack) { - AccuracyCard { - Text("Compare your ring with another device", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) - Text( - "Wear the ring and a watch or band you trust for a few days. PulseLoop reads that device's data from " + - "Health Connect and shows where the ring agrees and where it falls short.", - fontSize = 13.sp, color = PulseColors.textSecondary, - ) - Text( - "First step: see which apps share what with Health Connect. Starting a check comes in a later update.", - fontSize = 12.sp, color = PulseColors.textMuted, - ) - if (!available) { - Text("Health Connect isn't available on this phone.", fontSize = 12.sp, color = PulseColors.danger) - } else { - Row(horizontalArrangement = Arrangement.spacedBy(8.dp), verticalAlignment = Alignment.CenterVertically) { - if (readable.size < ReferenceMetric.entries.size) { - Button(onClick = { launcher.launch(AccuracyCheckPermissions.all) }, enabled = !scanning) { - Text(if (readable.isEmpty()) "Allow access" else "Allow more") + val current = open + when (current?.state) { + AccuracyCheckEntity.STATE_RUNNING -> RunningCard(current, scope) + AccuracyCheckEntity.STATE_AWAITING_RESUME -> ResumeCard(current, scope) + else -> {} + } + if (current != null) AccuracyReportSection(current) + + if (current == null) { + AccuracyCard { + Text("Compare your ring with another device", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + Text( + "Wear the ring and a watch or band you trust for a few days. PulseLoop reads that device's data from " + + "Health Connect and shows where the ring agrees and where it falls short.", + fontSize = 13.sp, color = PulseColors.textSecondary, + ) + Text( + "While a check runs, PulseLoop stops exporting the types the other device also writes, so Health Connect " + + "doesn't count your steps, sleep and heart rate twice.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + if (!available) { + Text("Health Connect isn't available on this phone.", fontSize = 12.sp, color = PulseColors.danger) + } else { + Row(horizontalArrangement = Arrangement.spacedBy(8.dp), verticalAlignment = Alignment.CenterVertically) { + if (readable.size < ReferenceMetric.entries.size) { + Button(onClick = { launcher.launch(AccuracyCheckPermissions.request) }, enabled = !scanning) { + Text(if (readable.isEmpty()) "Allow access" else "Allow more") + } } + if (readable.isNotEmpty()) { + OutlinedButton(onClick = { scan() }, enabled = !scanning) { Text("Scan last ${ReferenceSourceScanner.LOOKBACK_DAYS} days") } + } + if (scanning) CircularProgressIndicator(Modifier.size(20.dp), strokeWidth = 2.dp) } - if (readable.isNotEmpty()) { - OutlinedButton(onClick = { scan() }, enabled = !scanning) { Text("Scan last ${ReferenceSourceScanner.LOOKBACK_DAYS} days") } + } + if (!hasRing) Text("Pair your ring first: a check compares it against the other device.", fontSize = 12.sp, color = PulseColors.textMuted) + note?.let { Text(it, fontSize = 12.sp, color = PulseColors.warning) } + } + + val r = result + if (r != null) { + if (r.sources.isEmpty()) { + AccuracyCard { + Text("No other app wrote readable data in the last ${ReferenceSourceScanner.LOOKBACK_DAYS} days.", fontSize = 13.sp, color = PulseColors.textSecondary) + Text( + "If your watch syncs through an app like Health Sync, check that it's set to write to Health Connect.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) } - if (scanning) CircularProgressIndicator(Modifier.size(20.dp), strokeWidth = 2.dp) } + r.sources.forEach { src -> + SourceCard(context, src, onUse = if (hasRing && src.echo?.looksLikeEcho != true) ({ starting = src }) else null) + } + if (r.unreadable.isNotEmpty() || r.failed.isNotEmpty()) { + AccuracyCard { + if (r.unreadable.isNotEmpty()) { + Text("Not allowed to read: " + r.unreadable.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.textMuted) + } + if (r.failed.isNotEmpty()) { + Text("Couldn't read: " + r.failed.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.warning) + } + } + } + OutlinedButton(onClick = { + val text = ReferenceSurveyText.render(r.sources, ReferenceSourceScanner.LOOKBACK_DAYS, { ReferenceAppLabels.label(context, it) }, r.unreadable) + (context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager) + .setPrimaryClip(ClipData.newPlainText("Accuracy check sources", text)) + note = "Summary copied. It holds counts and timings only, no readings." + }, modifier = Modifier.fillMaxWidth()) { Text("Copy summary") } } - note?.let { Text(it, fontSize = 12.sp, color = PulseColors.warning) } } - val r = result - if (r != null) { - if (r.sources.isEmpty()) { - AccuracyCard { - Text("No other app wrote readable data in the last ${ReferenceSourceScanner.LOOKBACK_DAYS} days.", fontSize = 13.sp, color = PulseColors.textSecondary) - Text( - "If your watch syncs through an app like Health Sync, check that it's set to write to Health Connect.", - fontSize = 12.sp, color = PulseColors.textMuted, - ) + val past = history.filter { it.state == AccuracyCheckEntity.STATE_DONE } + if (past.isNotEmpty()) { + AccuracyCard { + Text("Past checks", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + past.forEach { c -> + Row( + Modifier.fillMaxWidth().clickable { viewing = c.id }.padding(vertical = 6.dp), + verticalAlignment = Alignment.CenterVertically, + ) { + Column(Modifier.weight(1f)) { + Text("${c.deviceLabel} vs ${c.referenceLabel}", fontSize = 13.sp, color = PulseColors.textPrimary) + Text(AccuracyUiText.span(c), fontSize = 12.sp, color = PulseColors.textMuted) + } + Text("View", fontSize = 13.sp, color = PulseColors.accent) + } } } - r.sources.forEach { SourceCard(context, it) } - if (r.unreadable.isNotEmpty() || r.failed.isNotEmpty()) { - AccuracyCard { - if (r.unreadable.isNotEmpty()) { - Text("Not allowed to read: " + r.unreadable.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.textMuted) + } + } + + starting?.let { src -> + StartDialog( + context = context, + source = src, + onDismiss = { starting = null }, + onStart = { label, days -> + scope.launch { + note = when (AccuracyCheckController.start(context, src, label, days)) { + is AccuracyCheckController.StartResult.Started -> null + AccuracyCheckController.StartResult.AlreadyOpen -> "A check is already open." + AccuracyCheckController.StartResult.NoRing -> "Pair your ring first." + AccuracyCheckController.StartResult.NothingToCompare -> "That app shares nothing PulseLoop can compare." } - if (r.failed.isNotEmpty()) { - Text("Couldn't read: " + r.failed.joinToString(", ") { it.label }, fontSize = 12.sp, color = PulseColors.warning) + starting = null + } + }, + ) + } +} + +/** Wording shared by the check screens. */ +internal object AccuracyUiText { + private val dateFmt = DateTimeFormatter.ofPattern("d MMM") + + fun date(ms: Long): String = Instant.ofEpochMilli(ms).atZone(ZoneId.systemDefault()).format(dateFmt) + + fun span(c: AccuracyCheckEntity): String = "${date(c.startedAt)} – ${date(c.endedAt ?: c.plannedEndAt)}" + + fun dayOf(c: AccuracyCheckEntity, now: Long = System.currentTimeMillis()): Pair { + val total = ((c.plannedEndAt - c.startedAt + 43_200_000L) / 86_400_000L).toInt().coerceAtLeast(1) + val day = ((now - c.startedAt) / 86_400_000L + 1).toInt().coerceIn(1, total) + return day to total + } + + fun endReason(c: AccuracyCheckEntity): String = when (c.endReason) { + AccuracyCheckEntity.END_RING_CHANGED -> "Ended early: a different ring was paired." + AccuracyCheckEntity.END_EARLY -> "Ended early." + else -> "Finished." + } + + fun units(units: Collection): String = + ExportUnit.entries.filter { it in units }.joinToString(", ") { it.metric.label.lowercase() }.replaceFirstChar { it.uppercase() } +} + +@Composable +private fun RunningCard(check: AccuracyCheckEntity, scope: kotlinx.coroutines.CoroutineScope) { + val context = LocalContext.current + val db = remember { PulseLoopDatabase.getInstance(context) } + val paused by db.accuracyDao().allPausedUnitsFlow().collectAsState(initial = emptyList()) + val units = paused.filter { it.checkId == check.id }.mapNotNull { ExportUnit.byName(it.unit) } + var confirmEnd by remember { mutableStateOf(false) } + val (day, total) = AccuracyUiText.dayOf(check) + AccuracyCard { + Text("Accuracy check · day $day of $total", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + Text("${check.deviceLabel} vs ${check.referenceLabel}, until ${AccuracyUiText.date(check.plannedEndAt)}.", fontSize = 13.sp, color = PulseColors.textSecondary) + Text("Wear both as usual. Health Connect export paused for: ${AccuracyUiText.units(units)}.", fontSize = 12.sp, color = PulseColors.warning) + OutlinedButton(onClick = { confirmEnd = true }) { Text("End now") } + } + if (confirmEnd) { + AlertDialog( + onDismissRequest = { confirmEnd = false }, + title = { Text("End the check now?") }, + text = { Text("The report covers the days so far. You'll then choose what happens to the paused Health Connect export.") }, + confirmButton = { + TextButton(onClick = { + confirmEnd = false + scope.launch { AccuracyCheckController.end(context, AccuracyCheckEntity.END_EARLY) } + }) { Text("End now") } + }, + dismissButton = { TextButton(onClick = { confirmEnd = false }) { Text("Keep going") } }, + ) + } +} + +@Composable +private fun ResumeCard(check: AccuracyCheckEntity, scope: kotlinx.coroutines.CoroutineScope) { + val context = LocalContext.current + var busy by remember { mutableStateOf(false) } + AccuracyCard { + Text("Check finished: resume Health Connect export", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + Text(AccuracyUiText.endReason(check) + " ${AccuracyUiText.span(check)}.", fontSize = 13.sp, color = PulseColors.textSecondary) + Text( + "During the check, ${check.referenceLabel} wrote the same types to Health Connect. Exporting the ring's copy " + + "of those days now would count them twice.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + Button(onClick = { + busy = true + scope.launch { AccuracyCheckController.resolve(context, AccuracyCheckEntity.RESUME_SKIP); busy = false } + }, enabled = !busy, modifier = Modifier.fillMaxWidth()) { Text("Skip these days (recommended)") } + OutlinedButton(onClick = { + busy = true + scope.launch { AccuracyCheckController.resolve(context, AccuracyCheckEntity.RESUME_EXPORT); busy = false } + }, enabled = !busy, modifier = Modifier.fillMaxWidth()) { Text("Export them too") } + Text( + "Export them too if you're taking the other device off and want the ring's full history in Health Connect.", + fontSize = 11.sp, color = PulseColors.textMuted, + ) + } +} + +@Composable +private fun StartDialog( + context: Context, + source: ReferenceSourceSurvey, + onDismiss: () -> Unit, + onStart: (label: String, days: Int) -> Unit, +) { + val defaultLabel = remember(source) { + val app = ReferenceAppLabels.label(context, source.packageName) + val model = source.devices.firstOrNull()?.let { listOfNotNull(it.manufacturer, it.model).joinToString(" ").trim() }?.takeIf { it.isNotBlank() } + if (model != null) "$app ($model)" else app + } + var label by remember { mutableStateOf(defaultLabel) } + var days by remember { mutableStateOf(AccuracyCheckController.DEFAULT_DAYS) } + val units = source.metrics.map { ExportUnit.of(it.metric) } + AlertDialog( + onDismissRequest = onDismiss, + title = { Text("Start an accuracy check") }, + text = { + Column(verticalArrangement = Arrangement.spacedBy(10.dp)) { + OutlinedTextField( + value = label, onValueChange = { label = it }, singleLine = true, + label = { Text("Reference device") }, + supportingText = if (source.packageName in ReferenceAppLabels.BRIDGES) { + { Text("A bridge app: name the watch behind it.") } + } else null, + ) + Text("How long", fontSize = 13.sp, fontWeight = FontWeight.SemiBold) + Row(horizontalArrangement = Arrangement.spacedBy(6.dp)) { + AccuracyCheckController.DURATIONS_DAYS.forEach { d -> + FilterChip(selected = days == d, onClick = { days = d }, label = { Text("$d days") }) } } + Text( + "Compared: ${AccuracyUiText.units(units)}. These stop exporting to Health Connect until the check ends " + + "and you choose what to do with those days.", + fontSize = 12.sp, + ) + Text("Wear both devices as you normally would, including at night.", fontSize = 12.sp) } - OutlinedButton(onClick = { - val text = ReferenceSurveyText.render(r.sources, ReferenceSourceScanner.LOOKBACK_DAYS, { ReferenceAppLabels.label(context, it) }, r.unreadable) - (context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager) - .setPrimaryClip(ClipData.newPlainText("Accuracy check sources", text)) - note = "Summary copied. It holds counts and timings only, no readings." - }, modifier = Modifier.fillMaxWidth()) { Text("Copy summary") } - } - } + }, + confirmButton = { TextButton(onClick = { onStart(label.trim(), days) }) { Text("Start") } }, + dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }, + ) } @Composable -private fun SourceCard(context: Context, s: ReferenceSourceSurvey) { +private fun SourceCard(context: Context, s: ReferenceSourceSurvey, onUse: (() -> Unit)? = null) { AccuracyCard { Text(ReferenceAppLabels.label(context, s.packageName), fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) Text(s.packageName, fontSize = 11.sp, color = PulseColors.textMuted) @@ -171,6 +381,7 @@ private fun SourceCard(context: Context, s: ReferenceSourceSurvey) { ) } s.metrics.forEach { MetricRow(it) } + if (onUse != null) Button(onClick = onUse, modifier = Modifier.fillMaxWidth()) { Text("Compare my ring with this") } } } @@ -201,3 +412,19 @@ private fun AccuracyCard(content: @Composable () -> Unit) { verticalArrangement = Arrangement.spacedBy(8.dp), ) { content() } } + +/** Today's one-line banner while a check is open. */ +@Composable +internal fun AccuracyCheckBanner(c: AccuracyCheckEntity, onOpen: () -> Unit) { + val text = if (c.state == AccuracyCheckEntity.STATE_RUNNING) { + val (day, total) = AccuracyUiText.dayOf(c) + "Accuracy check · day $day of $total · Health Connect export paused" + } else "Accuracy report ready · choose what to do with the paused export" + Row( + Modifier.fillMaxWidth().clip(RoundedCornerShape(8.dp)).background(PulseColors.card).clickable(onClick = onOpen).padding(12.dp), + verticalAlignment = Alignment.CenterVertically, + ) { + Text(text, fontSize = 12.sp, color = PulseColors.warning, modifier = Modifier.weight(1f)) + Text("Open", fontSize = 12.sp, color = PulseColors.accent) + } +} diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt new file mode 100644 index 00000000..412990ed --- /dev/null +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt @@ -0,0 +1,9 @@ +package com.pulseloop.ui.screens + +import androidx.compose.runtime.Composable +import com.pulseloop.data.entity.AccuracyCheckEntity + +/** The check's report. Filled in by the comparison engine (plan, Phase 2). */ +@Composable +internal fun AccuracyReportSection(check: AccuracyCheckEntity) { +} diff --git a/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt index d7390566..dc5a17b2 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/SettingsScreen.kt @@ -66,6 +66,13 @@ fun SettingsScreen( else -> keyStore.model } val notificationsTrailing = if (keyStore.notificationsEnabled) "On" else "Off" + val openCheck by db.accuracyDao().openFlow().collectAsState(initial = null) + val accuracyTrailing = openCheck?.let { c -> + if (c.state == com.pulseloop.data.entity.AccuracyCheckEntity.STATE_RUNNING) { + val (day, total) = AccuracyUiText.dayOf(c) + "Day $day of $total" + } else "Report ready" + } fun navigate(route: String) { navController?.navigate(route) @@ -170,7 +177,7 @@ fun SettingsScreen( add(SettingsRowItem(Icons.Filled.Sync, PulseColors.success, "Health Connect") { navigate("settings/health-connect") }) - add(SettingsRowItem(Icons.Filled.Verified, PulseColors.info, "Accuracy check") { + add(SettingsRowItem(Icons.Filled.Verified, PulseColors.info, "Accuracy check", accuracyTrailing) { navigate("settings/accuracy-check") }) add(SettingsRowItem(Icons.Filled.Info, PulseColors.textMuted, "About PulseLoop") { diff --git a/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt b/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt index 1dff1b3d..b6dab642 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/SettingsSubScreens.kt @@ -3396,6 +3396,12 @@ fun HealthConnectSettingsScreen(onBack: () -> Unit) { color = MaterialTheme.colorScheme.onSurfaceVariant, ) Spacer(Modifier.height(8.dp)) + // Accuracy check: rows whose records the reference device also writes are held + // back while a check runs (docs/accuracy-check-plan.md). The switch still works; + // the hold applies whatever it says, so it's shown as a note, not a disabled row. + val accuracyPaused by produceState(emptySet()) { + value = runCatching { com.pulseloop.health.accuracy.AccuracyCheckController.pausedNow(context) }.getOrDefault(emptySet()) + } val rows = listOf( HealthConnectPermissions.DataTypeRow.HEART_RATE to "Heart rate", HealthConnectPermissions.DataTypeRow.OXYGEN_SATURATION to "Oxygen saturation (SpO₂)", @@ -3442,6 +3448,16 @@ fun HealthConnectSettingsScreen(onBack: () -> Unit) { color = MaterialTheme.colorScheme.onSurfaceVariant, ) } + val heldUnits = accuracyPaused.filter { it.row == row } + if (heldUnits.isNotEmpty()) { + Text( + if (row == HealthConnectPermissions.DataTypeRow.STEPS_AND_ACTIVITY) { + "Paused by the accuracy check: " + heldUnits.joinToString(", ") { it.metric.label.lowercase() } + } else "Paused by the accuracy check", + style = MaterialTheme.typography.bodySmall, + color = PulseColors.warning, + ) + } } Switch(checked = prefs.toggleFor(row), enabled = rowGranted, onCheckedChange = null) } diff --git a/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt index b677fa94..6ae2195b 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt @@ -128,6 +128,7 @@ fun TodayScreen( } // Drinks, when the user tracks them: the tile and the morning-after line on Last night. var drinkTick by remember { mutableIntStateOf(0) } + val accuracyOpen by db.accuracyDao().openFlow().collectAsState(initial = null) val drinks by produceState(null, state.lastUpdated, sleep.lastNight?.id, drinkTick) { value = if (com.pulseloop.service.DrinkPrefs.enabled) runCatching { com.pulseloop.service.DrinksRepository.load(db) }.getOrNull() else null } @@ -216,6 +217,9 @@ fun TodayScreen( ) } + // Accuracy check in progress (docs/accuracy-check-plan.md): say so, since it pauses export. + accuracyOpen?.let { c -> item { AccuracyCheckBanner(c) { navController?.navigate("settings/accuracy-check") } } } + // Glance: one line of what today means, and an alert line only when something is off. item { val alert = guidance?.offSignals?.takeIf { com.pulseloop.service.VitalsCheck.shouldAlert(it) } diff --git a/app/src/test/java/com/pulseloop/health/HealthConnectPrefsStoreTest.kt b/app/src/test/java/com/pulseloop/health/HealthConnectPrefsStoreTest.kt index 9125f05b..578fd1c2 100644 --- a/app/src/test/java/com/pulseloop/health/HealthConnectPrefsStoreTest.kt +++ b/app/src/test/java/com/pulseloop/health/HealthConnectPrefsStoreTest.kt @@ -402,4 +402,27 @@ class HealthConnectPrefsStoreTest { assertNull(store.current.newOnlyConsentAt) assertTrue(store.current.newOnlyStamped) } + + @Test + fun rewindMovesOnlyBackwardsAndLeavesNeverExportedGroupsAlone() { + val store = storeWith("{\"enabled\":true,\"backfillChoice\":\"EXPORT_ALL\"}") + store.setWatermark(HealthConnectWatermarks.Key.VITALS, 5_000L) + store.setWatermark(HealthConnectWatermarks.Key.SLEEP, 1_000L) + store.rewindWatermarks( + setOf(HealthConnectWatermarks.Key.VITALS, HealthConnectWatermarks.Key.SLEEP, HealthConnectWatermarks.Key.ACTIVITY), + 2_000L, + ) + assertEquals(2_000L, store.currentWatermarks.vitals) + assertEquals(1_000L, store.currentWatermarks.sleep) // already earlier: untouched + assertNull(store.currentWatermarks.activity) // never exported: stays null + } + + @Test + fun rewindNeverCrossesANewOnlyUsersConsent() { + val store = storeWith("{\"enabled\":true}") + store.update { it.copy(backfillChoice = HealthConnectPrefs.BackfillChoice.EXPORT_NEW_ONLY, newOnlyConsentAt = 3_000L) } + store.setWatermark(HealthConnectWatermarks.Key.VITALS, 9_000L) + store.rewindWatermarks(setOf(HealthConnectWatermarks.Key.VITALS), 1_000L) + assertEquals(3_000L, store.currentWatermarks.vitals) + } } diff --git a/app/src/test/java/com/pulseloop/health/accuracy/ExportPauseTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/ExportPauseTest.kt new file mode 100644 index 00000000..96d81920 --- /dev/null +++ b/app/src/test/java/com/pulseloop/health/accuracy/ExportPauseTest.kt @@ -0,0 +1,130 @@ +package com.pulseloop.health.accuracy + +import androidx.health.connect.client.records.ExerciseSessionRecord +import androidx.health.connect.client.records.HeartRateRecord +import androidx.health.connect.client.records.OxygenSaturationRecord +import androidx.health.connect.client.records.Record +import androidx.health.connect.client.records.StepsRecord +import androidx.health.connect.client.records.metadata.Device +import androidx.health.connect.client.records.metadata.Metadata +import androidx.health.connect.client.units.Percentage +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.data.entity.AccuracyPausedUnitEntity +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test +import java.time.Instant +import java.time.ZoneOffset + +class ExportPauseTest { + + private val h = 3_600_000L + private val meta = Metadata.autoRecorded(Device(type = Device.TYPE_RING, manufacturer = "t", model = "t")) + + private fun hr(start: Long, end: Long = start + h) = HeartRateRecord( + startTime = Instant.ofEpochMilli(start), startZoneOffset = ZoneOffset.UTC, + endTime = Instant.ofEpochMilli(end), endZoneOffset = ZoneOffset.UTC, + samples = listOf(HeartRateRecord.Sample(Instant.ofEpochMilli(start), 60)), metadata = meta, + ) + + private fun steps(start: Long, end: Long) = StepsRecord( + startTime = Instant.ofEpochMilli(start), startZoneOffset = ZoneOffset.UTC, + endTime = Instant.ofEpochMilli(end), endZoneOffset = ZoneOffset.UTC, count = 100, metadata = meta, + ) + + private fun spo2(at: Long) = OxygenSaturationRecord( + time = Instant.ofEpochMilli(at), zoneOffset = ZoneOffset.UTC, percentage = Percentage(97.0), metadata = meta, + ) + + private fun workout(start: Long) = ExerciseSessionRecord( + startTime = Instant.ofEpochMilli(start), startZoneOffset = ZoneOffset.UTC, + endTime = Instant.ofEpochMilli(start + h), endZoneOffset = ZoneOffset.UTC, + exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_WALKING, metadata = meta, + ) + + private fun check(state: String, resume: String? = null, endedAt: Long? = null, id: String = "c") = AccuracyCheckEntity( + id = id, deviceKey = "AA", deviceLabel = "R11", referencePackage = "nl.appyhapps.healthsync", + referenceLabel = "Health Sync", startedAt = 10 * h, plannedEndAt = 100 * h, endedAt = endedAt, + state = state, resumeChoice = resume, + ) + + private fun paused(unit: ExportUnit, from: Long = 10 * h, id: String = "c") = AccuracyPausedUnitEntity(id, unit.name, from) + + @Test + fun anOpenCheckHoldsBackFromItsStartWithNoEnd() { + val ex = ExportPause.exclusions(listOf(check(AccuracyCheckEntity.STATE_RUNNING)), listOf(paused(ExportUnit.HEART_RATE))) + assertEquals(listOf(ExportExclusion(ExportUnit.HEART_RATE, 10 * h, null)), ex) + assertEquals(setOf(ExportUnit.HEART_RATE), ExportPause.pausedNow(ex)) + // Awaiting the resume choice still holds back: nothing is decided yet. + val waiting = ExportPause.exclusions(listOf(check(AccuracyCheckEntity.STATE_AWAITING_RESUME, endedAt = 50 * h)), listOf(paused(ExportUnit.HEART_RATE))) + assertNull(waiting.single().until) + } + + @Test + fun skipClosesTheWindowAtTheEndAndExportRemovesIt() { + val skip = ExportPause.exclusions( + listOf(check(AccuracyCheckEntity.STATE_DONE, AccuracyCheckEntity.RESUME_SKIP, 50 * h)), + listOf(paused(ExportUnit.STEPS)), + ) + assertEquals(listOf(ExportExclusion(ExportUnit.STEPS, 10 * h, 50 * h)), skip) + assertTrue(ExportPause.pausedNow(skip).isEmpty()) + val export = ExportPause.exclusions( + listOf(check(AccuracyCheckEntity.STATE_DONE, AccuracyCheckEntity.RESUME_EXPORT, 50 * h)), + listOf(paused(ExportUnit.STEPS)), + ) + assertTrue(export.isEmpty()) + } + + @Test + fun aUnitThatJoinedLateIsHeldBackOnlyFromWhenItJoined() { + val ex = ExportPause.exclusions( + listOf(check(AccuracyCheckEntity.STATE_RUNNING)), + listOf(paused(ExportUnit.HEART_RATE), paused(ExportUnit.OXYGEN_SATURATION, from = 30 * h)), + ) + val f = ExportPause.filter(listOf(spo2(20 * h), spo2(31 * h)), listOf(1, 2), ex) + assertEquals(1, f.records.size) + assertEquals(20 * h, (f.records.single() as OxygenSaturationRecord).time.toEpochMilli()) + } + + @Test + fun onlyThePausedTypeIsHeldBackAndTheWatermarkCanStillPassIt() { + val ex = listOf(ExportExclusion(ExportUnit.HEART_RATE, 10 * h, null)) + val records: List = listOf(hr(5 * h), hr(12 * h), spo2(12 * h), hr(13 * h), workout(12 * h)) + val f = ExportPause.filter(records, listOf(1, 2, 3, 4, 5), ex) + assertEquals(3, f.records.size) + assertEquals(listOf(1L, 3L, 5L), f.highWaters) + assertEquals(2, f.heldBack) + assertEquals(4L, f.heldBackHighWater) + // The workout session itself is never held back. + assertTrue(f.records.any { it is ExerciseSessionRecord }) + } + + @Test + fun aRecordOverlappingTheWindowEdgeIsHeldBack() { + val ex = listOf(ExportExclusion(ExportUnit.STEPS, 10 * h, 50 * h)) + // The whole day the check started on: its total includes in-window steps. + assertTrue(ExportPause.isHeldBack(steps(0, 24 * h), ex)) + // The day it ended on, likewise. + assertTrue(ExportPause.isHeldBack(steps(48 * h, 72 * h), ex)) + // Entirely before, entirely after. + assertFalse(ExportPause.isHeldBack(steps(0, 9 * h), ex)) + assertFalse(ExportPause.isHeldBack(steps(50 * h, 60 * h), ex)) + } + + @Test + fun noExclusionsIsAPassThrough() { + val records: List = listOf(hr(0), spo2(0)) + val f = ExportPause.filter(records, listOf(7, 8), emptyList()) + assertEquals(records, f.records) + assertNull(f.heldBackHighWater) + } + + @Test + fun everyExportUnitMapsBackToItsRecordTypeAndMetric() { + ReferenceMetric.entries.forEach { assertEquals(it, ExportUnit.of(it).metric) } + assertEquals(ExportUnit.STEPS, ExportUnit.ofRecord(steps(0, h))) + assertNull(ExportUnit.ofRecord(workout(0))) + } +} From e6c16868575f51ac5d2b5c6d31fe7fc8fc8c440a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 16:03:40 +0000 Subject: [PATCH 6/9] Accuracy check Phases 2-3: compare the ring with the reference and report 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 ', not 'is wrong by'. --- .../health/accuracy/AccuracyComparison.kt | 335 ++++++++++++++++ .../health/accuracy/AccuracyReportText.kt | 132 +++++++ .../health/accuracy/AccuracyScorer.kt | 370 ++++++++++++++++++ .../pulseloop/ui/screens/AccuracyCheckUi.kt | 2 +- .../pulseloop/ui/screens/AccuracyReportUi.kt | 269 ++++++++++++- .../health/accuracy/AccuracyComparisonTest.kt | 270 +++++++++++++ 6 files changed, 1375 insertions(+), 3 deletions(-) create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyComparison.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyScorer.kt create mode 100644 app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyComparison.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyComparison.kt new file mode 100644 index 00000000..e8c4e376 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyComparison.kt @@ -0,0 +1,335 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.data.entity.AccuracyCheckDayEntity +import java.time.Instant +import java.time.ZoneId +import kotlin.math.abs +import kotlin.math.sqrt + +/** + * What the report compares (docs/accuracy-check-plan.md, "Per metric"). [band] is the default + * agreement band — how close counts as agreeing — in [unit], or in percent when [percentBand]. + * [correction] is the form a fix for a consistent bias takes; null means the metric is + * report-only, because a difference there doesn't show which device is wrong (HRV and calories + * are computed differently by every vendor; sleep timing and stages are described, not adjusted). + */ +enum class ComparisonMetric( + val label: String, + val unit: String, + val kind: Kind, + val source: ReferenceMetric, + val band: Double, + val percentBand: Boolean, + val correction: CorrectionKind?, + /** Valid days (or nights) needed before a verdict. */ + val minDays: Int, + /** For paired metrics: pairs needed across the check. */ + val minPairs: Int = 0, +) { + STEPS("Steps", "steps", Kind.DAILY, ReferenceMetric.STEPS, 10.0, true, CorrectionKind.SCALE, 3), + DISTANCE("Distance", "m", Kind.DAILY, ReferenceMetric.DISTANCE, 15.0, true, CorrectionKind.SCALE, 3), + ACTIVE_CALORIES("Active calories", "kcal", Kind.DAILY, ReferenceMetric.ACTIVE_CALORIES, 25.0, true, null, 3), + SLEEP_ASLEEP("Time asleep", "min", Kind.DAILY, ReferenceMetric.SLEEP, 30.0, false, CorrectionKind.OFFSET, 3), + SLEEP_ONSET("Fell asleep", "min", Kind.DAILY, ReferenceMetric.SLEEP, 20.0, false, null, 3), + SLEEP_WAKE("Woke up", "min", Kind.DAILY, ReferenceMetric.SLEEP, 20.0, false, null, 3), + SLEEP_STAGES("Sleep stages", "min", Kind.STAGES, ReferenceMetric.SLEEP, 0.0, false, null, 3), + HR_REST("Heart rate at rest", "bpm", Kind.PAIRED, ReferenceMetric.HEART_RATE, 5.0, false, CorrectionKind.OFFSET, 3, 500), + HR_ACTIVE("Heart rate when active", "bpm", Kind.PAIRED, ReferenceMetric.HEART_RATE, 5.0, false, CorrectionKind.OFFSET, 2, 100), + RESTING_HR("Resting heart rate", "bpm", Kind.DAILY, ReferenceMetric.RESTING_HEART_RATE, 3.0, false, CorrectionKind.OFFSET, 3), + SPO2("Blood oxygen", "%", Kind.PAIRED, ReferenceMetric.OXYGEN_SATURATION, 2.0, false, CorrectionKind.OFFSET, 3, 30), + HRV("HRV", "ms", Kind.DAILY, ReferenceMetric.HRV, 10.0, false, null, 3), + ; + + enum class Kind { DAILY, PAIRED, STAGES } + + companion object { + fun byName(name: String): ComparisonMetric? = entries.firstOrNull { it.name == name } + fun forSource(m: ReferenceMetric): List = entries.filter { it.source == m } + } +} + +enum class CorrectionKind { SCALE, OFFSET } + +/** Sleep stages as both sides can express them. */ +enum class Stage { AWAKE, LIGHT, DEEP, REM, ASLEEP } + +data class StageSpan(val start: Long, val end: Long, val stage: Stage) + +/** One night, from either device. Without stage spans, the whole interval counts as asleep. */ +data class SleepNight(val start: Long, val end: Long, val spans: List) { + private val asleepSpans get() = spans.filter { it.stage != Stage.AWAKE } + val asleepMinutes: Int get() = + if (spans.isEmpty()) ((end - start) / 60_000L).toInt() + else (asleepSpans.sumOf { it.end - it.start } / 60_000L).toInt() + val onset: Long get() = asleepSpans.minOfOrNull { it.start } ?: start + val wake: Long get() = asleepSpans.maxOfOrNull { it.end } ?: end + val hasStages: Boolean get() = spans.any { it.stage == Stage.LIGHT || it.stage == Stage.DEEP || it.stage == Stage.REM } + + fun stageAt(t: Long): Stage? = spans.firstOrNull { t >= it.start && t < it.end }?.stage +} + +/** Running sums for paired samples, so days combine exactly. */ +data class PairSums(val n: Int = 0, val sumDiff: Double = 0.0, val sumSq: Double = 0.0, val sumAbs: Double = 0.0) { + operator fun plus(d: Double) = PairSums(n + 1, sumDiff + d, sumSq + d * d, sumAbs + abs(d)) + operator fun plus(o: PairSums) = PairSums(n + o.n, sumDiff + o.sumDiff, sumSq + o.sumSq, sumAbs + o.sumAbs) + val mean: Double get() = if (n == 0) 0.0 else sumDiff / n + val sd: Double get() = if (n < 2) 0.0 else sqrt(((sumSq - n * mean * mean) / (n - 1)).coerceAtLeast(0.0)) + val mae: Double get() = if (n == 0) 0.0 else sumAbs / n +} + +/** + * The comparison itself, pure (plan, "Comparison engine"): pairing, the sleep reductions, and the + * verdict. [AccuracyScorer] reads both devices' data and stores what this returns. + */ +object AccuracyComparison { + + const val DAY_MS = 86_400_000L + + fun epochDay(t: Long, zone: ZoneId): Long = Instant.ofEpochMilli(t).atZone(zone).toLocalDate().toEpochDay() + + // ── Pairing ──────────────────────────────────────────────────────────────────────────── + + /** + * Pairs each ring sample with the nearest reference sample within [toleranceMs] (each + * reference sample used once at most), and sums the differences `ring − reference` per + * (day, context). [contextOf] returns null to skip a sample. Both lists sorted by time. + */ + fun pair( + ring: List, + ref: List, + toleranceMs: Long, + zone: ZoneId, + contextOf: (Long) -> C?, + ): Map, PairSums> { + val out = linkedMapOf, PairSums>() + if (ring.isEmpty() || ref.isEmpty()) return out + val used = BooleanArray(ref.size) + var j = 0 + for (s in ring) { + while (j < ref.size && ref[j].at < s.at - toleranceMs) j++ + var best = -1 + var bestDt = Long.MAX_VALUE + var k = j + while (k < ref.size && ref[k].at <= s.at + toleranceMs) { + val dt = abs(ref[k].at - s.at) + if (!used[k] && dt < bestDt) { best = k; bestDt = dt } + k++ + } + if (best < 0) continue + val ctx = contextOf(s.at) ?: continue + used[best] = true + val key = epochDay(s.at, zone) to ctx + out[key] = (out[key] ?: PairSums()) + (s.value - ref[best].value) + } + return out + } + + /** + * Pairing tolerance from the reference's own cadence: a sparse reference (a bridge relaying + * one heart rate every few minutes) gets a wider window, up to [maxMs], since a fixed 60 s + * would pair almost nothing; a dense one keeps it tight. + */ + fun tolerance(refMedianIntervalMs: Long?, minMs: Long, maxMs: Long): Long = + ((refMedianIntervalMs ?: minMs) / 2).coerceIn(minMs, maxMs) + + // ── Reference totals ─────────────────────────────────────────────────────────────────── + + /** An interval total (steps, metres, kcal) split across local days in proportion to overlap. */ + data class IntervalAmount(val start: Long, val end: Long, val amount: Double) + + fun dailyTotals(items: List, zone: ZoneId): Map { + val out = mutableMapOf() + for (it in items) { + if (it.end <= it.start) { + out.merge(epochDay(it.start, zone), it.amount, Double::plus) + continue + } + var t = it.start + val len = (it.end - it.start).toDouble() + while (t < it.end) { + val day = epochDay(t, zone) + val dayEnd = java.time.LocalDate.ofEpochDay(day).plusDays(1).atStartOfDay(zone).toInstant().toEpochMilli() + val segEnd = minOf(dayEnd, it.end) + out.merge(day, it.amount * (segEnd - t) / len, Double::plus) + t = segEnd + } + } + return out + } + + // ── Sleep ────────────────────────────────────────────────────────────────────────────── + + data class StageAgreement(val overlapMinutes: Int, val agreeMinutes: Int, val confusion: Map, Int>) { + /** "LIGHT>DEEP:30,…" — ring stage > reference stage : minutes. */ + fun encode(): String = confusion.entries.sortedBy { it.key.first.ordinal * 10 + it.key.second.ordinal } + .joinToString(",") { "${it.key.first}>${it.key.second}:${it.value}" } + + companion object { + fun decode(s: String?): Map, Int> = s.orEmpty().split(',').mapNotNull { part -> + val (k, v) = part.split(':').takeIf { it.size == 2 } ?: return@mapNotNull null + val (a, b) = k.split('>').takeIf { it.size == 2 } ?: return@mapNotNull null + val sa = runCatching { Stage.valueOf(a) }.getOrNull() ?: return@mapNotNull null + val sb = runCatching { Stage.valueOf(b) }.getOrNull() ?: return@mapNotNull null + (sa to sb) to (v.toIntOrNull() ?: return@mapNotNull null) + }.toMap() + } + } + + /** + * Minute by minute over the stretch both nights cover, counting only minutes where both name + * a stage (an unstaged "asleep" can't agree or disagree with "deep"). Null when either side + * has no stages. + */ + fun stageAgreement(ring: SleepNight, ref: SleepNight): StageAgreement? { + if (!ring.hasStages || !ref.hasStages) return null + val from = maxOf(ring.start, ref.start) + val to = minOf(ring.end, ref.end) + val confusion = mutableMapOf, Int>() + var overlap = 0 + var agree = 0 + var t = from + while (t + 60_000L <= to) { + val mid = t + 30_000L + val a = ring.stageAt(mid) + val b = ref.stageAt(mid) + if (a != null && b != null && a != Stage.ASLEEP && b != Stage.ASLEEP) { + overlap++ + if (a == b) agree++ + confusion.merge(a to b, 1, Int::plus) + } + t += 60_000L + } + return StageAgreement(overlap, agree, confusion) + } + + // ── Day rows ─────────────────────────────────────────────────────────────────────────── + + /** A daily-total row: one value each side; the difference is in percent for a percent metric. */ + fun dailyRow( + checkId: String, + metric: ComparisonMetric, + day: Long, + ring: Double?, + ref: Double?, + valid: Boolean, + note: String? = null, + now: Long, + ): AccuracyCheckDayEntity { + val d = diff(metric, ring, ref) + return AccuracyCheckDayEntity( + checkId = checkId, metric = metric.name, day = day, ringValue = ring, refValue = ref, + pairs = if (d != null) 1 else 0, sumDiff = d ?: 0.0, sumSqDiff = (d ?: 0.0) * (d ?: 0.0), sumAbsDiff = abs(d ?: 0.0), + inBand = if (d != null && abs(d) <= metric.band) 1 else 0, + valid = valid && d != null, note = note, computedAt = now, + ) + } + + fun pairedRow(checkId: String, metric: ComparisonMetric, day: Long, sums: PairSums, valid: Boolean, now: Long, note: String? = null) = + AccuracyCheckDayEntity( + checkId = checkId, metric = metric.name, day = day, pairs = sums.n, + sumDiff = sums.sumDiff, sumSqDiff = sums.sumSq, sumAbsDiff = sums.sumAbs, + valid = valid, note = note, computedAt = now, + ) + + fun diff(metric: ComparisonMetric, ring: Double?, ref: Double?): Double? { + if (ring == null || ref == null) return null + return if (metric.percentBand) { + if (ref <= 0.0) null else (ring - ref) / ref * 100.0 + } else ring - ref + } + + // ── Verdict ──────────────────────────────────────────────────────────────────────────── + + enum class Verdict { AGREES, CONSISTENTLY_HIGH, CONSISTENTLY_LOW, INCONSISTENT, NOT_ENOUGH_DATA } + + data class Summary( + val metric: ComparisonMetric, + val verdict: Verdict, + val validDays: Int, + /** Mean difference ring − reference (percent for a percent metric). */ + val bias: Double, + /** Spread of the differences: SD across days (daily) or across pairs (paired). */ + val sd: Double, + val mae: Double, + val pairs: Int, + /** Share of days whose own difference points the same way as [bias]. */ + val sameSignShare: Double, + /** Suggested correction (scale factor or offset), when the verdict is a consistent bias. */ + val suggestedCorrection: Double?, + val band: Double, + /** Sleep stages only: minutes on the same stage over minutes compared. */ + val stageAgreement: Double? = null, + ) { + /** Bland-Altman 95 % limits of agreement. */ + val limits: Pair get() = (bias - 1.96 * sd) to (bias + 1.96 * sd) + } + + /** + * Bias vs noise (plan, "Two ideas behind every metric"). Agreement needs the average inside + * the band and the spread not far outside it. A consistent bias needs the average outside the + * band, most days pointing the same way, and the day-to-day wobble of that bias smaller than + * the bias itself — only then will a single correction help. Anything else is inconsistent: + * no correction is offered, because one would just move the average of an erratic ring. + */ + fun summarize(metric: ComparisonMetric, days: List, band: Double = metric.band): Summary { + val valid = days.filter { it.valid && it.metric == metric.name && it.pairs > 0 } + if (metric.kind == ComparisonMetric.Kind.STAGES) { + val overlap = valid.sumOf { it.pairs } + val agree = valid.sumOf { it.inBand } + val share = if (overlap > 0) agree.toDouble() / overlap else null + return Summary( + metric, if (valid.size < metric.minDays) Verdict.NOT_ENOUGH_DATA else Verdict.AGREES, + valid.size, 0.0, 0.0, 0.0, overlap, 0.0, null, band, stageAgreement = share, + ) + } + val dayBiases = valid.map { it.sumDiff / it.pairs } + val (bias, sd, mae, pairs) = if (metric.kind == ComparisonMetric.Kind.PAIRED) { + val s = valid.fold(PairSums()) { acc, d -> acc + PairSums(d.pairs, d.sumDiff, d.sumSqDiff, d.sumAbsDiff) } + Quad(s.mean, s.sd, s.mae, s.n) + } else { + val m = dayBiases.average().takeIf { !it.isNaN() } ?: 0.0 + Quad(m, sdOf(dayBiases), dayBiases.map { abs(it) }.average().takeIf { !it.isNaN() } ?: 0.0, valid.size) + } + val sameSign = if (dayBiases.isEmpty() || bias == 0.0) 0.0 + else dayBiases.count { it * bias > 0 }.toDouble() / dayBiases.size + val enough = valid.size >= metric.minDays && pairs >= metric.minPairs + val noiseOk = if (metric.kind == ComparisonMetric.Kind.PAIRED) mae <= band * 1.5 else sd <= band * 1.5 + val verdict = when { + !enough -> Verdict.NOT_ENOUGH_DATA + abs(bias) <= band && noiseOk -> Verdict.AGREES + abs(bias) > band && sameSign >= 0.8 && sdOf(dayBiases) < abs(bias) -> + if (bias > 0) Verdict.CONSISTENTLY_HIGH else Verdict.CONSISTENTLY_LOW + else -> Verdict.INCONSISTENT + } + val suggestion = if (metric.correction != null && (verdict == Verdict.CONSISTENTLY_HIGH || verdict == Verdict.CONSISTENTLY_LOW)) { + when (metric.correction) { + CorrectionKind.SCALE -> { + val ring = valid.sumOf { it.ringValue ?: 0.0 } + val ref = valid.sumOf { it.refValue ?: 0.0 } + if (ring > 0) ref / ring else null + } + CorrectionKind.OFFSET -> -bias + } + } else null + return Summary(metric, verdict, valid.size, bias, sd, mae, pairs, sameSign, suggestion, band) + } + + private data class Quad(val a: Double, val b: Double, val c: Double, val d: Int) + + private fun sdOf(xs: List): Double { + if (xs.size < 2) return 0.0 + val m = xs.average() + return sqrt(xs.sumOf { (it - m) * (it - m) } / (xs.size - 1)) + } + + // ── Bands ────────────────────────────────────────────────────────────────────────────── + + fun parseBands(raw: String?): Map = raw.orEmpty().split(';').mapNotNull { part -> + val (k, v) = part.split('=').takeIf { it.size == 2 } ?: return@mapNotNull null + val m = ComparisonMetric.byName(k) ?: return@mapNotNull null + m to (v.toDoubleOrNull()?.takeIf { it > 0 } ?: return@mapNotNull null) + }.toMap() + + fun encodeBands(bands: Map): String? = + bands.filter { (m, v) -> v != m.band }.entries.joinToString(";") { "${it.key.name}=${it.value}" }.ifEmpty { null } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt new file mode 100644 index 00000000..2afaaddb --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt @@ -0,0 +1,132 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.health.accuracy.AccuracyComparison.Summary +import com.pulseloop.health.accuracy.AccuracyComparison.Verdict +import kotlin.math.abs +import kotlin.math.roundToInt + +/** + * The report's words (plan, "The report"). Says "differs from ", never "is wrong by": + * the reference is the device the user chose to trust, not ground truth. + */ +object AccuracyReportText { + + fun verdictLabel(v: Verdict): String = when (v) { + Verdict.AGREES -> "Agrees" + Verdict.CONSISTENTLY_HIGH -> "Consistently high" + Verdict.CONSISTENTLY_LOW -> "Consistently low" + Verdict.INCONSISTENT -> "Inconsistent" + Verdict.NOT_ENOUGH_DATA -> "Not enough data" + } + + /** A signed difference in the metric's own terms: "−18 %", "+25 min", "+3.2 bpm". */ + fun signed(m: ComparisonMetric, d: Double): String { + val sign = if (d < 0) "−" else "+" + val a = abs(d) + return sign + magnitude(m, a) + } + + fun magnitude(m: ComparisonMetric, a: Double): String = when (m) { + ComparisonMetric.STEPS, ComparisonMetric.DISTANCE, ComparisonMetric.ACTIVE_CALORIES -> "${a.roundToInt()} %" + ComparisonMetric.SLEEP_ASLEEP, ComparisonMetric.SLEEP_ONSET, ComparisonMetric.SLEEP_WAKE -> minutes(a) + ComparisonMetric.HR_REST, ComparisonMetric.HR_ACTIVE, ComparisonMetric.RESTING_HR -> "%.1f bpm".format(a) + ComparisonMetric.SPO2 -> "%.1f points".format(a) + ComparisonMetric.HRV -> "${a.roundToInt()} ms" + ComparisonMetric.SLEEP_STAGES -> "${a.roundToInt()} min" + } + + fun minutes(a: Double): String { + val m = a.roundToInt() + return if (m < 60) "$m min" else "${m / 60} h ${m % 60} min" + } + + /** A value as one device read it, for the per-day rows. */ + fun value(m: ComparisonMetric, v: Double?): String { + if (v == null) return "—" + return when (m) { + ComparisonMetric.STEPS -> "%,d".format(v.roundToInt()) + ComparisonMetric.DISTANCE -> "%.2f km".format(v / 1000.0) + ComparisonMetric.ACTIVE_CALORIES -> "${v.roundToInt()} kcal" + ComparisonMetric.SLEEP_ASLEEP -> minutes(v) + ComparisonMetric.SLEEP_ONSET, ComparisonMetric.SLEEP_WAKE -> clock(v) + ComparisonMetric.RESTING_HR -> "%.0f bpm".format(v) + ComparisonMetric.HRV -> "${v.roundToInt()} ms" + else -> "%.1f".format(v) + } + } + + /** Minutes from the waking day's midnight (negative = the evening before) as a clock time. */ + fun clock(minutesFromMidnight: Double): String { + val m = Math.floorMod(minutesFromMidnight.roundToInt(), 24 * 60) + return "%02d:%02d".format(m / 60, m % 60) + } + + private fun higher(m: ComparisonMetric): Pair = when (m) { + ComparisonMetric.STEPS -> "more steps" to "fewer steps" + ComparisonMetric.DISTANCE -> "more distance" to "less distance" + ComparisonMetric.ACTIVE_CALORIES -> "more active calories" to "fewer active calories" + ComparisonMetric.SLEEP_ASLEEP -> "more time asleep" to "less time asleep" + ComparisonMetric.SLEEP_ONSET -> "you fell asleep later" to "you fell asleep earlier" + ComparisonMetric.SLEEP_WAKE -> "you woke later" to "you woke earlier" + else -> "higher" to "lower" + } + + /** The one-line reading under a card's headline. */ + fun reading(s: Summary, ref: String): String { + val m = s.metric + if (m == ComparisonMetric.SLEEP_STAGES) { + val share = s.stageAgreement + return when { + s.verdict == Verdict.NOT_ENOUGH_DATA -> "Not enough nights with stages from both devices yet (${s.validDays} of ${m.minDays})." + share == null -> "No minutes to compare." + else -> "Both name the same stage for ${(share * 100).roundToInt()} % of the night. Stages are described, not corrected: " + + "vendors stage sleep differently." + } + } + val nightly = m.source == ReferenceMetric.SLEEP || m == ComparisonMetric.RESTING_HR || m == ComparisonMetric.HRV + fun count(n: Int) = "$n ${if (nightly) "night" else "day"}${if (n == 1) "" else "s"}" + val days = count(s.validDays) + val (up, down) = higher(m) + val dirWord = if (s.bias > 0) up else down + val amount = magnitude(m, abs(s.bias)) + val isTiming = m == ComparisonMetric.SLEEP_ONSET || m == ComparisonMetric.SLEEP_WAKE + return when (s.verdict) { + Verdict.NOT_ENOUGH_DATA -> if (s.pairs < m.minPairs && s.validDays >= m.minDays) { + "Not enough matching readings yet (${s.pairs} of ${m.minPairs})." + } else "Not enough data yet: $days of ${m.minDays} needed." + Verdict.AGREES -> "Agrees with $ref: ${signed(m, s.bias)} on average over $days, inside the ±${magnitude(m, s.band)} band." + Verdict.CONSISTENTLY_HIGH, Verdict.CONSISTENTLY_LOW -> { + val share = (s.sameSignShare * s.validDays).roundToInt() + val what = when { + isTiming -> "By about $amount, the ring says $dirWord than $ref" + m.kind == ComparisonMetric.Kind.PAIRED || m == ComparisonMetric.RESTING_HR || m == ComparisonMetric.HRV -> + "Your ring reads about $amount $dirWord than $ref" + else -> "Your ring records about $amount $dirWord than $ref" + } + "$what, on $share of ${count(s.validDays)}." + + if (m.correction != null) " A correction would help." else "" + } + Verdict.INCONSISTENT -> { + val (lo, hi) = s.limits + "Differs from $ref by ${magnitude(m, s.mae)} on average, in no steady direction " + + "(usually between ${signed(m, lo)} and ${signed(m, hi)}). A single correction can't fix that." + } + } + } + + /** Why a day doesn't count, for the per-day rows. */ + fun dayNote(note: String?, ref: String): String? = when (note) { + AccuracyScorer.NOTE_WAITING -> "waiting for $ref to deliver" + AccuracyScorer.NOTE_NOT_WORN -> "not worn on both" + AccuracyScorer.NOTE_NO_REF_NIGHT -> "no night from $ref" + AccuracyScorer.NOTE_NO_REF_STAGES -> "$ref gave no stages" + AccuracyScorer.NOTE_FEW_PAIRS -> "too few matching readings" + else -> null + } + + /** Worst first: how far outside its band each failing metric is. */ + fun worstFirst(summaries: List): List = summaries + .filter { it.verdict == Verdict.CONSISTENTLY_HIGH || it.verdict == Verdict.CONSISTENTLY_LOW || it.verdict == Verdict.INCONSISTENT } + .filter { it.metric.kind != ComparisonMetric.Kind.STAGES } + .sortedByDescending { maxOf(abs(it.bias), it.mae) / it.band.coerceAtLeast(1e-6) } +} diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyScorer.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyScorer.kt new file mode 100644 index 00000000..920f7a12 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyScorer.kt @@ -0,0 +1,370 @@ +package com.pulseloop.health.accuracy + +import android.content.Context +import android.util.Log +import androidx.health.connect.client.HealthConnectClient +import androidx.health.connect.client.records.ActiveCaloriesBurnedRecord +import androidx.health.connect.client.records.DistanceRecord +import androidx.health.connect.client.records.HeartRateRecord +import androidx.health.connect.client.records.HeartRateVariabilityRmssdRecord +import androidx.health.connect.client.records.OxygenSaturationRecord +import androidx.health.connect.client.records.Record +import androidx.health.connect.client.records.RestingHeartRateRecord +import androidx.health.connect.client.records.SleepSessionRecord +import androidx.health.connect.client.records.StepsRecord +import androidx.health.connect.client.records.metadata.DataOrigin +import androidx.health.connect.client.request.ReadRecordsRequest +import androidx.health.connect.client.time.TimeRangeFilter +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckDayEntity +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.data.entity.SleepStageBlockEntity +import com.pulseloop.health.HealthConnectAvailability +import com.pulseloop.health.HealthConnectSdk +import com.pulseloop.ring.MeasurementKind +import com.pulseloop.ring.SleepStage +import com.pulseloop.service.DailyCalorieEstimator +import com.pulseloop.service.NightlyVitals +import com.pulseloop.service.VitalSample +import com.pulseloop.service.asleepMinutes +import com.pulseloop.util.TimeUtil +import java.time.Instant +import java.time.LocalDate +import java.time.ZoneId +import kotlin.reflect.KClass + +/** + * Reads both devices for a check's window and stores the scored days (plan, "Comparison + * engine"). Foreground: it reads Health Connect, which background quotas make unreliable. The + * reference's readings are reduced to [AccuracyCheckDayEntity] aggregates here and never stored. + */ +object AccuracyScorer { + + private const val TAG = "AccuracyScorer" + private const val HOUR = 3_600_000L + /** A reference day with fewer steps than this is a day the device wasn't worn, not a ring overcount. */ + const val MIN_REF_STEPS = 500.0 + /** A 15-minute bucket with this many steps or more is "active" for heart rate. */ + const val ACTIVE_BUCKET_STEPS = 300 + /** …and with fewer than this it's "at rest". In between is ambiguous and not scored. */ + const val REST_BUCKET_STEPS = 50 + const val MIN_HR_PAIRS_PER_DAY = 20 + const val MIN_SPO2_PAIRS_PER_DAY = 5 + /** A day is scored once the reference has delivered past its end, or after this long anyway. */ + const val DELIVERY_GRACE_MS = 24 * HOUR + /** Don't re-read more often than this unless asked. */ + const val RESCORE_INTERVAL_MS = 30 * 60_000L + + enum class HrContext { REST, ACTIVE } + + sealed interface Result { + data class Scored(val rows: Int, val waitingDays: Int, val echo: EchoCheck?) : Result + data object Unavailable : Result + data object Skipped : Result + } + + suspend fun scoreIfStale(context: Context, check: AccuracyCheckEntity, now: Long = System.currentTimeMillis()): Result = + if (check.scoredAt != null && now - check.scoredAt < RESCORE_INTERVAL_MS) Result.Skipped else score(context, check, now) + + suspend fun score(context: Context, check: AccuracyCheckEntity, now: Long = System.currentTimeMillis()): Result { + if (HealthConnectSdk.availability(context) != HealthConnectAvailability.AVAILABLE) return Result.Unavailable + val db = PulseLoopDatabase.getInstance(context) + val dao = db.accuracyDao() + val client = HealthConnectClient.getOrCreate(context) + val zone = ZoneId.systemDefault() + val from = check.startedAt + val to = check.endedAt ?: minOf(now, check.plannedEndAt) + val readable = AccuracyCheckPermissions.readable(ReferenceSourceScanner.grantedPermissions(context)) + val compared = dao.pausedUnits(check.id).mapNotNull { ExportUnit.byName(it.unit)?.metric }.toSet() intersect readable + val origin = setOf(DataOrigin(check.referencePackage)) + val readFrom = from - 18 * HOUR // a night that began before the check's first morning + val readTo = to + 18 * HOUR + + suspend fun read(type: KClass): List { + val out = mutableListOf() + var token: String? = null + var pages = 0 + do { + val r = client.readRecords( + ReadRecordsRequest( + type, + TimeRangeFilter.between(Instant.ofEpochMilli(readFrom), Instant.ofEpochMilli(readTo)), + dataOriginFilter = origin, pageSize = 1000, pageToken = token, + ), + ) + out += r.records + token = r.pageToken + pages++ + } while (token != null && pages < 40) + return out + } + + val ref = try { + RefData( + steps = if (ReferenceMetric.STEPS in compared) read(StepsRecord::class) else emptyList(), + distance = if (ReferenceMetric.DISTANCE in compared) read(DistanceRecord::class) else emptyList(), + calories = if (ReferenceMetric.ACTIVE_CALORIES in compared) read(ActiveCaloriesBurnedRecord::class) else emptyList(), + hr = if (ReferenceMetric.HEART_RATE in compared) read(HeartRateRecord::class) else emptyList(), + resting = if (ReferenceMetric.RESTING_HEART_RATE in compared) read(RestingHeartRateRecord::class) else emptyList(), + sleep = if (ReferenceMetric.SLEEP in compared) read(SleepSessionRecord::class) else emptyList(), + spo2 = if (ReferenceMetric.OXYGEN_SATURATION in compared) read(OxygenSaturationRecord::class) else emptyList(), + hrv = if (ReferenceMetric.HRV in compared) read(HeartRateVariabilityRmssdRecord::class) else emptyList(), + ) + } catch (e: Exception) { + Log.w(TAG, "reading the reference failed", e) + return Result.Unavailable + } + + val refHr = ref.hr.flatMap { r -> r.samples.map { TimedValue(it.time.toEpochMilli(), it.beatsPerMinute.toDouble()) } }.sortedBy { it.at } + // The latest data time the reference has delivered, across everything it wrote. + val coveredUntil = listOfNotNull( + ref.steps.maxOfOrNull { it.endTime.toEpochMilli() }, + ref.distance.maxOfOrNull { it.endTime.toEpochMilli() }, + refHr.lastOrNull()?.at, + ref.sleep.maxOfOrNull { it.endTime.toEpochMilli() }, + ref.spo2.maxOfOrNull { it.time.toEpochMilli() }, + ).maxOrNull() ?: 0L + fun delivered(dataEnd: Long) = coveredUntil >= dataEnd - 30 * 60_000L || now >= dataEnd + DELIVERY_GRACE_MS + + val rows = mutableListOf() + var waiting = 0 + val ringHrAll = db.measurementDao().rangeReal(MeasurementKind.HEART_RATE.name, readFrom, readTo) + val ringHr = ringHrAll.filter { it.timestamp in from..to }.map { TimedValue(it.timestamp, it.value) } + + // ── Daily totals: whole local days inside the window only. The day a check starts on is + // partial for whichever device went on later, so its totals aren't comparable. + val fullDays = fullDaysIn(from, to, zone) + val refSteps = AccuracyComparison.dailyTotals(ref.steps.map { AccuracyComparison.IntervalAmount(it.startTime.toEpochMilli(), it.endTime.toEpochMilli(), it.count.toDouble()) }, zone) + val refDist = AccuracyComparison.dailyTotals(ref.distance.map { AccuracyComparison.IntervalAmount(it.startTime.toEpochMilli(), it.endTime.toEpochMilli(), it.distance.inMeters) }, zone) + val refCal = AccuracyComparison.dailyTotals(ref.calories.map { AccuracyComparison.IntervalAmount(it.startTime.toEpochMilli(), it.endTime.toEpochMilli(), it.energy.inKilocalories) }, zone) + for (day in fullDays) { + val dayStart = LocalDate.ofEpochDay(day).atStartOfDay(zone).toInstant().toEpochMilli() + val dayEnd = LocalDate.ofEpochDay(day).plusDays(1).atStartOfDay(zone).toInstant().toEpochMilli() + val ringDay = db.activityDailyDao().byDay(dayStart)?.takeIf { it.source != "demo" && it.source != "mock" } + val isDelivered = delivered(dayEnd) + if (!isDelivered) waiting++ + val refStepsDay = refSteps[day] + // Worn on both: the reference walked a real day and the ring recorded something. + val worn = (refStepsDay ?: 0.0) >= MIN_REF_STEPS && (ringDay?.steps ?: 0) > 0 + val note = when { + !isDelivered -> NOTE_WAITING + !worn -> NOTE_NOT_WORN + else -> null + } + if (ReferenceMetric.STEPS in compared) { + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.STEPS, day, ringDay?.steps?.toDouble(), refStepsDay, isDelivered && worn, note, now) + } + if (ReferenceMetric.DISTANCE in compared) { + val ringDist = ringDay?.distanceMeters?.takeIf { it > 0 } + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.DISTANCE, day, ringDist, refDist[day], isDelivered && (worn || ReferenceMetric.STEPS !in compared), note, now) + } + if (ReferenceMetric.ACTIVE_CALORIES in compared) { + val ringCal = ringDay?.let { DailyCalorieEstimator.effectiveActiveCalories(it) } + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.ACTIVE_CALORIES, day, ringCal, refCal[day], isDelivered && (worn || ReferenceMetric.STEPS !in compared), note, now) + } + } + + // ── Sleep, per waking day. The ring's main night is its longest session that day, the + // same night Readiness uses. + val ringNights = ringNights(db, from, to, zone) + val needsNights = ReferenceMetric.SLEEP in compared || ReferenceMetric.RESTING_HEART_RATE in compared || ReferenceMetric.HRV in compared + val refNights = ref.sleep.groupBy { AccuracyComparison.epochDay(TimeUtil.wakingDayLocal(it.startTime.toEpochMilli(), zone), zone) } + .mapValues { (_, s) -> s.maxBy { it.endTime.toEpochMilli() - it.startTime.toEpochMilli() } } + val ringHrv = if (needsNights) db.measurementDao().rangeReal(MeasurementKind.HRV.name, readFrom, readTo) else emptyList() + for ((day, night) in ringNights) { + val dayMidnight = LocalDate.ofEpochDay(day).atStartOfDay(zone).toInstant().toEpochMilli() + val isDelivered = delivered(night.session.endAt) + if (ReferenceMetric.SLEEP in compared) { + val refRec = refNights[day] + val refNight = refRec?.let(::toNight) + val note = when { + !isDelivered -> NOTE_WAITING + refNight == null -> NOTE_NO_REF_NIGHT + else -> null + } + val valid = isDelivered && refNight != null + val ringAsleep = (if (night.blocks.isEmpty()) night.session.totalMinutes else asleepMinutes(night.blocks)).toDouble() + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.SLEEP_ASLEEP, day, ringAsleep, refNight?.asleepMinutes?.toDouble(), valid, note, now) + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.SLEEP_ONSET, day, + minutesFrom(dayMidnight, night.night.onset), refNight?.let { minutesFrom(dayMidnight, it.onset) }, valid, note, now) + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.SLEEP_WAKE, day, + minutesFrom(dayMidnight, night.night.wake), refNight?.let { minutesFrom(dayMidnight, it.wake) }, valid, note, now) + val agreement = refNight?.let { AccuracyComparison.stageAgreement(night.night, it) } + if (agreement != null || refNight != null) { + rows += AccuracyCheckDayEntity( + checkId = check.id, metric = ComparisonMetric.SLEEP_STAGES.name, day = day, + pairs = agreement?.overlapMinutes ?: 0, inBand = agreement?.agreeMinutes ?: 0, + valid = valid && agreement != null && agreement.overlapMinutes > 0, + note = agreement?.encode() ?: if (refNight != null && !refNight.hasStages) NOTE_NO_REF_STAGES else note, + computedAt = now, + ) + } + } + if (ReferenceMetric.RESTING_HEART_RATE in compared || ReferenceMetric.HRV in compared) { + val summary = NightlyVitals.summarize( + day = LocalDate.ofEpochDay(day), startAt = night.session.startAt, endAt = night.session.endAt, + asleepMinutes = asleepMinutes(night.blocks), + heartRate = ringHrAll.map { VitalSample(it.timestamp, it.value) }, + hrv = ringHrv.map { VitalSample(it.timestamp, it.value) }, + ) + if (ReferenceMetric.RESTING_HEART_RATE in compared) { + val refRhr = ref.resting.filter { AccuracyComparison.epochDay(it.time.toEpochMilli(), zone) == day } + .maxByOrNull { it.time }?.beatsPerMinute?.toDouble() + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.RESTING_HR, day, summary.restingHr, refRhr, + isDelivered, if (!isDelivered) NOTE_WAITING else null, now) + } + if (ReferenceMetric.HRV in compared) { + val window = (night.session.startAt - HOUR)..(night.session.endAt + HOUR) + val refHrvNight = ref.hrv.filter { it.time.toEpochMilli() in window }.map { it.heartRateVariabilityMillis }.sorted() + val refMedian = refHrvNight.takeIf { it.isNotEmpty() }?.let { it[it.size / 2] } + rows += AccuracyComparison.dailyRow(check.id, ComparisonMetric.HRV, day, summary.hrv, refMedian, + isDelivered, if (!isDelivered) NOTE_WAITING else null, now) + } + } + } + + // ── Heart rate, paired sample by sample and split rest / active. + var echo: EchoCheck? = null + if (ReferenceMetric.HEART_RATE in compared && refHr.isNotEmpty()) { + echo = ReferenceSurveyBuilder.echoCheck(refHr, ringHr) + val tol = AccuracyComparison.tolerance(ReferenceSurveyBuilder.medianInterval(refHr.map { it.at }), 60_000L, 150_000L) + val buckets = fullDaysOrPartial(from, to, zone).flatMap { d -> + db.activityBucketDao().byDay(LocalDate.ofEpochDay(d).atStartOfDay(zone).toInstant().toEpochMilli()) + }.associateBy { it.startEpoch } + val workouts = db.activitySessionDao().finishedSince(from).filter { it.endedAt != null && it.startedAt < to } + val sleepWindows = ringNights.values.map { it.session.startAt..it.session.endAt } + val pairs = AccuracyComparison.pair(ringHr, refHr, tol, zone) { t -> + when { + workouts.any { t >= it.startedAt && t <= it.endedAt!! } -> HrContext.ACTIVE + sleepWindows.any { t in it } -> HrContext.REST + else -> { + val steps = buckets[t - Math.floorMod(t, 15 * 60_000L)]?.steps ?: 0 + when { + steps >= ACTIVE_BUCKET_STEPS -> HrContext.ACTIVE + steps < REST_BUCKET_STEPS -> HrContext.REST + else -> null + } + } + } + } + for ((key, sums) in pairs) { + val (day, ctx) = key + val dayEnd = LocalDate.ofEpochDay(day).plusDays(1).atStartOfDay(zone).toInstant().toEpochMilli() + val metric = if (ctx == HrContext.REST) ComparisonMetric.HR_REST else ComparisonMetric.HR_ACTIVE + val isDelivered = delivered(minOf(dayEnd, to)) + val enough = sums.n >= if (ctx == HrContext.REST) MIN_HR_PAIRS_PER_DAY else 5 + rows += AccuracyComparison.pairedRow(check.id, metric, day, sums, isDelivered && enough, now, + when { !isDelivered -> NOTE_WAITING; !enough -> NOTE_FEW_PAIRS; else -> null }) + } + } + + // ── SpO₂, paired within five minutes. + if (ReferenceMetric.OXYGEN_SATURATION in compared && ref.spo2.isNotEmpty()) { + val ringSpo2 = db.measurementDao().rangeReal(MeasurementKind.SPO2.name, from, to) + .filter { it.value in 70.0..100.0 }.map { TimedValue(it.timestamp, it.value) } + val refSpo2 = ref.spo2.map { TimedValue(it.time.toEpochMilli(), it.percentage.value) }.sortedBy { it.at } + val pairs = AccuracyComparison.pair(ringSpo2, refSpo2, 5 * 60_000L, zone) { Unit } + for ((key, sums) in pairs) { + val day = key.first + val dayEnd = LocalDate.ofEpochDay(day).plusDays(1).atStartOfDay(zone).toInstant().toEpochMilli() + val isDelivered = delivered(minOf(dayEnd, to)) + rows += AccuracyComparison.pairedRow(check.id, ComparisonMetric.SPO2, day, sums, + isDelivered && sums.n >= MIN_SPO2_PAIRS_PER_DAY, now, if (!isDelivered) NOTE_WAITING else null) + } + } + + echo?.let { + rows += AccuracyCheckDayEntity(checkId = check.id, metric = ECHO_ROW, day = 0, pairs = it.compared, inBand = it.matching, valid = false, computedAt = now) + } + + dao.clearDays(check.id) + dao.upsertDays(rows) + dao.byId(check.id)?.let { dao.upsert(it.copy(scoredAt = now)) } + return Result.Scored(rows.size, waiting, echo) + } + + const val ECHO_ROW = "ECHO" + const val NOTE_WAITING = "waiting" + const val NOTE_NOT_WORN = "not_worn" + const val NOTE_NO_REF_NIGHT = "no_ref_night" + const val NOTE_NO_REF_STAGES = "no_ref_stages" + const val NOTE_FEW_PAIRS = "few_pairs" + + private data class RefData( + val steps: List, + val distance: List, + val calories: List, + val hr: List, + val resting: List, + val sleep: List, + val spo2: List, + val hrv: List, + ) + + private data class RingNight( + val session: com.pulseloop.data.entity.SleepSessionEntity, + val blocks: List, + val night: SleepNight, + ) + + /** Ring nights that started at or after the check began and ended by its end, by waking epoch day. */ + private suspend fun ringNights(db: PulseLoopDatabase, from: Long, to: Long, zone: ZoneId): Map { + val sessions = db.sleepSessionDao().inRangeReal(TimeUtil.startOfDayLocal(from, zone), to + AccuracyComparison.DAY_MS) + .filter { it.totalMinutes > 0 && it.startAt >= from && it.endAt <= to } + .groupBy { it.date } + .mapValues { (_, s) -> s.maxBy { it.totalMinutes } } + return sessions.values.associate { s -> + val blocks = db.sleepStageBlockDao().forSession(s.id) + AccuracyComparison.epochDay(s.date, zone) to RingNight(s, blocks, SleepNight(s.startAt, s.endAt, blocks.map(::toSpan))) + } + } + + internal fun toSpan(b: SleepStageBlockEntity): StageSpan = StageSpan( + b.startAt, b.startAt + b.durationMinutes * 60_000L, + when (b.stageRaw) { + SleepStage.AWAKE.name -> Stage.AWAKE + SleepStage.LIGHT.name -> Stage.LIGHT + SleepStage.DEEP.name -> Stage.DEEP + SleepStage.REM.name -> Stage.REM + else -> Stage.ASLEEP + }, + ) + + internal fun toNight(r: SleepSessionRecord): SleepNight = SleepNight( + r.startTime.toEpochMilli(), r.endTime.toEpochMilli(), + r.stages.map { s -> + StageSpan( + s.startTime.toEpochMilli(), s.endTime.toEpochMilli(), + when (s.stage) { + SleepSessionRecord.STAGE_TYPE_AWAKE, SleepSessionRecord.STAGE_TYPE_OUT_OF_BED, + SleepSessionRecord.STAGE_TYPE_AWAKE_IN_BED -> Stage.AWAKE + SleepSessionRecord.STAGE_TYPE_LIGHT -> Stage.LIGHT + SleepSessionRecord.STAGE_TYPE_DEEP -> Stage.DEEP + SleepSessionRecord.STAGE_TYPE_REM -> Stage.REM + else -> Stage.ASLEEP + }, + ) + }, + ) + + private fun minutesFrom(origin: Long, t: Long): Double = (t - origin) / 60_000.0 + + /** Local days lying wholly inside `[from, to]`. */ + internal fun fullDaysIn(from: Long, to: Long, zone: ZoneId): List { + val first = Instant.ofEpochMilli(from).atZone(zone).toLocalDate() + val firstFull = if (first.atStartOfDay(zone).toInstant().toEpochMilli() == from) first else first.plusDays(1) + val out = mutableListOf() + var d = firstFull + while (d.plusDays(1).atStartOfDay(zone).toInstant().toEpochMilli() <= to) { + out += d.toEpochDay() + d = d.plusDays(1) + } + return out + } + + private fun fullDaysOrPartial(from: Long, to: Long, zone: ZoneId): List { + val a = Instant.ofEpochMilli(from).atZone(zone).toLocalDate().toEpochDay() + val b = Instant.ofEpochMilli(to).atZone(zone).toLocalDate().toEpochDay() + return (a..b).toList() + } +} diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt index e7ee4e7b..f3456296 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt @@ -406,7 +406,7 @@ private fun MetricRow(m: MetricSurvey) { } @Composable -private fun AccuracyCard(content: @Composable () -> Unit) { +internal fun AccuracyCard(content: @Composable () -> Unit) { Column( Modifier.fillMaxWidth().clip(RoundedCornerShape(8.dp)).background(PulseColors.card).padding(16.dp), verticalArrangement = Arrangement.spacedBy(8.dp), diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt index 412990ed..9c8284c9 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt @@ -1,9 +1,274 @@ package com.pulseloop.ui.screens +import androidx.compose.foundation.background +import androidx.compose.foundation.clickable +import androidx.compose.foundation.layout.Arrangement +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.Row +import androidx.compose.foundation.layout.fillMaxWidth +import androidx.compose.foundation.layout.padding +import androidx.compose.foundation.layout.size +import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.material3.CircularProgressIndicator +import androidx.compose.material3.Slider +import androidx.compose.material3.Text +import androidx.compose.material3.TextButton import androidx.compose.runtime.Composable +import androidx.compose.runtime.LaunchedEffect +import androidx.compose.runtime.collectAsState +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope +import androidx.compose.runtime.setValue +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.draw.clip +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.platform.LocalContext +import androidx.compose.ui.text.font.FontWeight +import androidx.compose.ui.unit.dp +import androidx.compose.ui.unit.sp +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckDayEntity import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.health.accuracy.AccuracyComparison +import com.pulseloop.health.accuracy.AccuracyComparison.Verdict +import com.pulseloop.health.accuracy.AccuracyReportText +import com.pulseloop.health.accuracy.AccuracyScorer +import com.pulseloop.health.accuracy.ComparisonMetric +import com.pulseloop.health.accuracy.EchoCheck +import com.pulseloop.health.accuracy.Stage +import com.pulseloop.ui.theme.PulseColors +import kotlinx.coroutines.launch +import java.time.LocalDate +import java.time.format.DateTimeFormatter +import kotlin.math.roundToInt -/** The check's report. Filled in by the comparison engine (plan, Phase 2). */ +/** + * A check's report (docs/accuracy-check-plan.md, "The report"): one card per metric with a + * verdict, the metrics outside their band listed worst first, and per-day detail behind a tap. + * Bands are editable and the verdicts recompute from the stored day rows, with no new read. + * [correctionFor] lets the corrections UI hang a control under a metric with a consistent bias. + */ @Composable -internal fun AccuracyReportSection(check: AccuracyCheckEntity) { +internal fun AccuracyReportSection( + check: AccuracyCheckEntity, + correctionFor: (@Composable (AccuracyComparison.Summary) -> Unit)? = { AccuracyCorrectionControl(check, it) }, +) { + val context = LocalContext.current + val scope = rememberCoroutineScope() + val db = remember { PulseLoopDatabase.getInstance(context) } + val days by db.accuracyDao().daysFlow(check.id).collectAsState(initial = emptyList()) + var scoring by remember { mutableStateOf(false) } + var status by remember { mutableStateOf(null) } + var expanded by remember { mutableStateOf(null) } + val bands = AccuracyComparison.parseBands(check.bandsRaw) + + fun rescore(force: Boolean) { + scoring = true + scope.launch { + val r = runCatching { + if (force) AccuracyScorer.score(context, check) else AccuracyScorer.scoreIfStale(context, check) + }.getOrNull() + status = when (r) { + AccuracyScorer.Result.Unavailable, null -> "Couldn't read ${check.referenceLabel} from Health Connect just now." + else -> null + } + scoring = false + } + } + // An open check refreshes on view. A finished one keeps its stored result, unless days were + // still waiting for the reference to deliver when it was last scored. + LaunchedEffect(check.id) { + val waiting = db.accuracyDao().days(check.id).any { it.note == AccuracyScorer.NOTE_WAITING } + if (check.isOpen || check.scoredAt == null || waiting) rescore(force = false) + } + + val metrics = ComparisonMetric.entries.filter { m -> days.any { it.metric == m.name } } + val summaries = metrics.map { AccuracyComparison.summarize(it, days, bands[it] ?: it.band) } + val echoRow = days.firstOrNull { it.metric == AccuracyScorer.ECHO_ROW } + val echo = echoRow?.let { EchoCheck(it.pairs, it.inBand) } + val waitingDays = days.filter { it.note == AccuracyScorer.NOTE_WAITING }.map { it.day }.distinct().size + + AccuracyCard { + Row(verticalAlignment = Alignment.CenterVertically) { + Text( + if (check.state == AccuracyCheckEntity.STATE_RUNNING) "So far (preliminary)" else "Report", + fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary, modifier = Modifier.weight(1f), + ) + if (scoring) CircularProgressIndicator(Modifier.size(18.dp), strokeWidth = 2.dp) + else TextButton(onClick = { rescore(force = true) }) { Text("Recompute") } + } + Text( + "How your ring compares with ${check.referenceLabel}, the device you chose to trust. This is agreement between two " + + "consumer devices, not a lab measurement.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + if (echo?.looksLikeEcho == true) { + Text( + "${echo.matching} of ${echo.compared} heart-rate readings from ${check.referenceLabel} match your ring exactly. " + + "That looks like PulseLoop's own data coming back through a sync app, so this report would compare the ring " + + "with itself. Check the sync direction in that app.", + fontSize = 12.sp, color = PulseColors.danger, + ) + } + if (waitingDays > 0) { + Text( + "Waiting for ${check.referenceLabel} to deliver $waitingDays day${if (waitingDays == 1) "" else "s"}. Open the app " + + "that syncs it to send it sooner; otherwise those days are scored 24 hours after they end.", + fontSize = 12.sp, color = PulseColors.warning, + ) + } + status?.let { Text(it, fontSize = 12.sp, color = PulseColors.warning) } + if (days.isEmpty() && !scoring) { + Text("Nothing to compare yet. Check back after the first full day and night.", fontSize = 13.sp, color = PulseColors.textSecondary) + } + val worst = AccuracyReportText.worstFirst(summaries) + if (worst.isNotEmpty()) { + Text("Where the ring falls short", fontSize = 13.sp, fontWeight = FontWeight.SemiBold, color = PulseColors.textPrimary) + worst.forEach { s -> + Text("• ${s.metric.label}: ${AccuracyReportText.signed(s.metric, s.bias)} (${AccuracyReportText.verdictLabel(s.verdict).lowercase()})", + fontSize = 12.sp, color = PulseColors.textSecondary) + } + } else if (summaries.isNotEmpty() && summaries.none { it.verdict == Verdict.NOT_ENOUGH_DATA }) { + Text("Everything compared agrees within its band.", fontSize = 13.sp, color = PulseColors.success) + } + } + + summaries.forEach { s -> + MetricCard( + check = check, + summary = s, + days = days.filter { it.metric == s.metric.name }.sortedBy { it.day }, + expanded = expanded == s.metric, + onToggle = { expanded = if (expanded == s.metric) null else s.metric }, + onBand = { v -> + val next = bands.toMutableMap().apply { put(s.metric, v) } + scope.launch { db.accuracyDao().upsert(check.copy(bandsRaw = AccuracyComparison.encodeBands(next))) } + }, + correction = correctionFor, + ) + } +} + +private fun verdictColor(v: Verdict): Color = when (v) { + Verdict.AGREES -> PulseColors.success + Verdict.CONSISTENTLY_HIGH, Verdict.CONSISTENTLY_LOW -> PulseColors.warning + Verdict.INCONSISTENT -> PulseColors.danger + Verdict.NOT_ENOUGH_DATA -> PulseColors.textMuted +} + +@Composable +private fun MetricCard( + check: AccuracyCheckEntity, + summary: AccuracyComparison.Summary, + days: List, + expanded: Boolean, + onToggle: () -> Unit, + onBand: (Double) -> Unit, + correction: (@Composable (AccuracyComparison.Summary) -> Unit)?, +) { + val m = summary.metric + AccuracyCard { + Row(Modifier.fillMaxWidth().clickable(onClick = onToggle), verticalAlignment = Alignment.CenterVertically) { + Column(Modifier.weight(1f)) { + Text(m.label, fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + val headline = when { + summary.verdict == Verdict.NOT_ENOUGH_DATA -> null + m.kind == ComparisonMetric.Kind.STAGES -> summary.stageAgreement?.let { "${(it * 100).roundToInt()} % same stage" } + else -> AccuracyReportText.signed(m, summary.bias) + " vs ${check.referenceLabel}" + } + headline?.let { Text(it, fontSize = 13.sp, color = PulseColors.textSecondary) } + } + Text( + AccuracyReportText.verdictLabel(summary.verdict), + fontSize = 12.sp, color = verdictColor(summary.verdict), + modifier = Modifier.clip(RoundedCornerShape(10.dp)).background(PulseColors.cardSoft).padding(horizontal = 8.dp, vertical = 3.dp), + ) + } + Text(AccuracyReportText.reading(summary, check.referenceLabel), fontSize = 12.sp, color = PulseColors.textSecondary) + if (summary.verdict == Verdict.CONSISTENTLY_HIGH || summary.verdict == Verdict.CONSISTENTLY_LOW) { + correction?.invoke(summary) + } + if (!expanded) { + Text("Details", fontSize = 12.sp, color = PulseColors.accent, modifier = Modifier.clickable(onClick = onToggle)) + return@AccuracyCard + } + if (m.kind != ComparisonMetric.Kind.STAGES && summary.validDays > 0) { + val (lo, hi) = summary.limits + Text( + "Average difference ${AccuracyReportText.signed(m, summary.bias)}; 95 % of differences between " + + "${AccuracyReportText.signed(m, lo)} and ${AccuracyReportText.signed(m, hi)}" + + if (m.kind == ComparisonMetric.Kind.PAIRED) " (${summary.pairs} matched readings)." else ".", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + } + if (m.kind == ComparisonMetric.Kind.STAGES) StageConfusion(days, check.referenceLabel) + days.forEach { DayRow(m, it, check.referenceLabel) } + if (m.kind != ComparisonMetric.Kind.STAGES) { + Text("Agreement band: ±${AccuracyReportText.magnitude(m, summary.band)}", fontSize = 12.sp, color = PulseColors.textPrimary) + var draft by remember(summary.band) { mutableStateOf(summary.band.toFloat()) } + val range = bandRange(m) + Slider( + value = draft.coerceIn(range.start, range.endInclusive), onValueChange = { draft = it }, + onValueChangeFinished = { onBand(roundBand(m, draft.toDouble())) }, valueRange = range, + ) + } + } +} + +private fun bandRange(m: ComparisonMetric): ClosedFloatingPointRange = when { + m.percentBand -> 2f..40f + m == ComparisonMetric.SLEEP_ASLEEP -> 5f..90f + m == ComparisonMetric.SLEEP_ONSET || m == ComparisonMetric.SLEEP_WAKE -> 5f..60f + m == ComparisonMetric.SPO2 -> 0.5f..5f + m == ComparisonMetric.HRV -> 2f..30f + else -> 1f..15f +} + +private fun roundBand(m: ComparisonMetric, v: Double): Double = + if (m == ComparisonMetric.SPO2) (v * 2).roundToInt() / 2.0 else v.roundToInt().toDouble().coerceAtLeast(1.0) + +@Composable +private fun DayRow(m: ComparisonMetric, d: AccuracyCheckDayEntity, ref: String) { + val date = LocalDate.ofEpochDay(d.day).format(DateTimeFormatter.ofPattern("EEE d MMM")) + val note = if (d.valid) null else AccuracyReportText.dayNote(d.note, ref) ?: "not counted" + val text = when (m.kind) { + ComparisonMetric.Kind.DAILY -> { + val diff = AccuracyComparison.diff(m, d.ringValue, d.refValue) + "$date · ring ${AccuracyReportText.value(m, d.ringValue)} · $ref ${AccuracyReportText.value(m, d.refValue)}" + + (diff?.let { " (${AccuracyReportText.signed(m, it)})" } ?: "") + } + ComparisonMetric.Kind.PAIRED -> + "$date · ${d.pairs} readings · ${if (d.pairs > 0) AccuracyReportText.signed(m, d.sumDiff / d.pairs) else "—"} on average" + ComparisonMetric.Kind.STAGES -> + "$date · ${if (d.pairs > 0) "${(d.inBand * 100.0 / d.pairs).roundToInt()} % of ${d.pairs} min on the same stage" else "no overlap"}" + } + Text(text + (note?.let { " — $it" } ?: ""), fontSize = 12.sp, color = if (d.valid) PulseColors.textSecondary else PulseColors.textMuted) +} + +@Composable +private fun StageConfusion(days: List, ref: String) { + val totals = mutableMapOf, Int>() + days.filter { it.valid }.forEach { d -> + AccuracyComparison.StageAgreement.decode(d.note).forEach { (k, v) -> totals.merge(k, v, Int::plus) } + } + if (totals.isEmpty()) return + val stages = listOf(Stage.AWAKE, Stage.LIGHT, Stage.DEEP, Stage.REM) + Text("When the ring says… what $ref says (minutes)", fontSize = 12.sp, fontWeight = FontWeight.SemiBold, color = PulseColors.textPrimary) + stages.forEach { ringStage -> + val row = stages.map { totals[ringStage to it] ?: 0 } + if (row.sum() == 0) return@forEach + Text( + "${ringStage.name.lowercase()}: " + stages.zip(row).filter { it.second > 0 } + .joinToString(", ") { "${it.first.name.lowercase()} ${it.second}" }, + fontSize = 12.sp, color = PulseColors.textSecondary, + ) + } +} + +/** Filled in by the corrections phase; shows nothing until then. */ +@Composable +internal fun AccuracyCorrectionControl(check: AccuracyCheckEntity, summary: AccuracyComparison.Summary) { } diff --git a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt new file mode 100644 index 00000000..f9e0174c --- /dev/null +++ b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt @@ -0,0 +1,270 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.data.entity.AccuracyCheckDayEntity +import com.pulseloop.health.accuracy.AccuracyComparison.Verdict +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test +import java.time.LocalDate +import java.time.ZoneId +import java.time.ZoneOffset + +class AccuracyComparisonTest { + + private val utc: ZoneId = ZoneOffset.UTC + private val min = 60_000L + private val h = 60 * min + private val day0 = LocalDate.of(2026, 10, 1).atStartOfDay(utc).toInstant().toEpochMilli() + + private fun daily(metric: ComparisonMetric, day: Long, ring: Double, ref: Double, valid: Boolean = true) = + AccuracyComparison.dailyRow("c", metric, day, ring, ref, valid, null, 0) + + // ── pairing ── + + @Test + fun eachReferenceSampleIsUsedOnceAndOnlyWithinTolerance() { + val ring = listOf(TimedValue(0, 60.0), TimedValue(10_000, 62.0), TimedValue(200_000, 70.0)) + val ref = listOf(TimedValue(5_000, 58.0), TimedValue(400_000, 90.0)) + val pairs = AccuracyComparison.pair(ring, ref, 60_000, utc) { Unit } + val sums = pairs.values.single() + // Only the first ring sample gets the 5 s reference sample; the second finds it used, the + // third has nothing within a minute. + assertEquals(1, sums.n) + assertEquals(2.0, sums.sumDiff, 1e-9) + } + + @Test + fun pairsSplitByDayAndContext_andANullContextIsSkipped() { + val ring = listOf(TimedValue(day0 + h, 50.0), TimedValue(day0 + 2 * h, 100.0), TimedValue(day0 + 25 * h, 52.0), TimedValue(day0 + 3 * h, 80.0)) + .sortedBy { it.at } + val ref = ring.map { TimedValue(it.at + 1_000, it.value - 2) } + val pairs = AccuracyComparison.pair(ring, ref, 60_000, utc) { t -> + when (t) { + day0 + 3 * h -> null + day0 + 2 * h -> "active" + else -> "rest" + } + } + val d0 = LocalDate.of(2026, 10, 1).toEpochDay() + assertEquals(1, pairs[d0 to "rest"]!!.n) + assertEquals(1, pairs[d0 to "active"]!!.n) + assertEquals(1, pairs[d0 + 1 to "rest"]!!.n) + assertEquals(3, pairs.values.sumOf { it.n }) + } + + @Test + fun aSparseReferenceWidensThePairingWindowUpToItsCap() { + assertEquals(60_000L, AccuracyComparison.tolerance(null, 60_000, 150_000)) + assertEquals(60_000L, AccuracyComparison.tolerance(30_000, 60_000, 150_000)) + assertEquals(120_000L, AccuracyComparison.tolerance(240_000, 60_000, 150_000)) + assertEquals(150_000L, AccuracyComparison.tolerance(600_000, 60_000, 150_000)) + } + + @Test + fun pairSumsCombineExactly() { + val a = PairSums() + 1.0 + 3.0 + val b = PairSums() + -2.0 + val all = a + b + assertEquals(3, all.n) + assertEquals(2.0 / 3, all.mean, 1e-9) + assertEquals(2.0, all.mae, 1e-9) + } + + // ── reference totals ── + + @Test + fun anIntervalCrossingMidnightIsSplitByOverlap() { + val totals = AccuracyComparison.dailyTotals( + listOf(AccuracyComparison.IntervalAmount(day0 + 23 * h, day0 + 25 * h, 200.0)), utc, + ) + val d0 = LocalDate.of(2026, 10, 1).toEpochDay() + assertEquals(100.0, totals[d0]!!, 1e-9) + assertEquals(100.0, totals[d0 + 1]!!, 1e-9) + } + + // ── sleep ── + + @Test + fun aNightWithoutStagesCountsItsWholeSpanAsAsleep() { + val n = SleepNight(0, 8 * h, emptyList()) + assertEquals(480, n.asleepMinutes) + assertEquals(0L, n.onset) + assertEquals(8 * h, n.wake) + assertFalse(n.hasStages) + } + + @Test + fun onsetAndWakeIgnoreAwakeAtTheEdges() { + val n = SleepNight(0, 8 * h, listOf( + StageSpan(0, 20 * min, Stage.AWAKE), + StageSpan(20 * min, 7 * h, Stage.LIGHT), + StageSpan(7 * h, 8 * h, Stage.AWAKE), + )) + assertEquals(20 * min, n.onset) + assertEquals(7 * h, n.wake) + assertEquals(400, n.asleepMinutes) + } + + @Test + fun stageAgreementCountsOnlyMinutesBothSidesStage() { + val ring = SleepNight(0, 4 * h, listOf(StageSpan(0, 2 * h, Stage.LIGHT), StageSpan(2 * h, 4 * h, Stage.DEEP))) + val ref = SleepNight(h, 5 * h, listOf( + StageSpan(h, 3 * h, Stage.LIGHT), + StageSpan(3 * h, 3 * h + 30 * min, Stage.ASLEEP), // unstaged: neither agrees nor disagrees + StageSpan(3 * h + 30 * min, 5 * h, Stage.DEEP), + )) + val a = AccuracyComparison.stageAgreement(ring, ref)!! + // Overlap 1h–4h is 180 min, minus 30 unstaged. + assertEquals(150, a.overlapMinutes) + // light/light 60 (1h–2h) + deep/deep 30 (3h30–4h); deep/light 60 (2h–3h). + assertEquals(90, a.agreeMinutes) + assertEquals(60, a.confusion[Stage.DEEP to Stage.LIGHT]) + assertEquals(a.confusion, AccuracyComparison.StageAgreement.decode(a.encode())) + } + + @Test + fun noStagesOnEitherSideMeansNoStageAgreement() { + val staged = SleepNight(0, h, listOf(StageSpan(0, h, Stage.LIGHT))) + assertNull(AccuracyComparison.stageAgreement(staged, SleepNight(0, h, emptyList()))) + } + + // ── verdicts ── + + @Test + fun aSteadyUndercountIsConsistentlyLowWithAScaleSuggestion() { + val days = (0 until 6).map { daily(ComparisonMetric.STEPS, it.toLong(), 8_000.0 + it * 100, (8_000.0 + it * 100) / 0.8) } + val s = AccuracyComparison.summarize(ComparisonMetric.STEPS, days) + assertEquals(Verdict.CONSISTENTLY_LOW, s.verdict) + assertEquals(-20.0, s.bias, 0.01) + assertEquals(1.25, s.suggestedCorrection!!, 0.001) + assertEquals(1.0, s.sameSignShare, 1e-9) + } + + @Test + fun anErraticRingIsInconsistentAndGetsNoCorrection() { + val ring = listOf(10_000.0, 6_000.0, 12_500.0, 7_000.0, 11_000.0, 6_500.0) + val days = ring.mapIndexed { i, r -> daily(ComparisonMetric.STEPS, i.toLong(), r, 9_000.0) } + val s = AccuracyComparison.summarize(ComparisonMetric.STEPS, days) + assertEquals(Verdict.INCONSISTENT, s.verdict) + assertNull(s.suggestedCorrection) + } + + @Test + fun aSmallDifferenceAgrees() { + val days = (0 until 4).map { daily(ComparisonMetric.STEPS, it.toLong(), 9_300.0, 9_000.0) } + assertEquals(Verdict.AGREES, AccuracyComparison.summarize(ComparisonMetric.STEPS, days).verdict) + } + + @Test + fun tooFewValidDaysIsNotEnoughData_andInvalidDaysDontCount() { + val days = listOf( + daily(ComparisonMetric.STEPS, 0, 5_000.0, 9_000.0), + daily(ComparisonMetric.STEPS, 1, 5_000.0, 9_000.0), + daily(ComparisonMetric.STEPS, 2, 100.0, 9_000.0, valid = false), + ) + val s = AccuracyComparison.summarize(ComparisonMetric.STEPS, days) + assertEquals(Verdict.NOT_ENOUGH_DATA, s.verdict) + assertEquals(2, s.validDays) + } + + @Test + fun pairedHeartRateWithASteadyOffsetGetsAnOffsetSuggestion() { + val days = (0 until 4).map { d -> + val sums = (0 until 200).fold(PairSums()) { acc, i -> acc + (6.0 + (i % 5 - 2) * 0.5) } + AccuracyComparison.pairedRow("c", ComparisonMetric.HR_REST, d.toLong(), sums, true, 0) + } + val s = AccuracyComparison.summarize(ComparisonMetric.HR_REST, days) + assertEquals(Verdict.CONSISTENTLY_HIGH, s.verdict) + assertEquals(800, s.pairs) + assertEquals(-6.0, s.suggestedCorrection!!, 0.01) + } + + @Test + fun pairedButTooFewReadingsIsNotEnough() { + val days = (0 until 4).map { AccuracyComparison.pairedRow("c", ComparisonMetric.HR_REST, it.toLong(), PairSums() + 8.0, true, 0) } + assertEquals(Verdict.NOT_ENOUGH_DATA, AccuracyComparison.summarize(ComparisonMetric.HR_REST, days).verdict) + } + + @Test + fun aWiderBandTurnsABiasIntoAgreement() { + val days = (0 until 4).map { daily(ComparisonMetric.SLEEP_ASLEEP, it.toLong(), 420.0, 380.0) } + assertEquals(Verdict.CONSISTENTLY_HIGH, AccuracyComparison.summarize(ComparisonMetric.SLEEP_ASLEEP, days).verdict) + assertEquals(Verdict.AGREES, AccuracyComparison.summarize(ComparisonMetric.SLEEP_ASLEEP, days, band = 45.0).verdict) + } + + @Test + fun reportOnlyMetricsNeverSuggestACorrection() { + val days = (0 until 5).map { daily(ComparisonMetric.HRV, it.toLong(), 60.0, 30.0) } + val s = AccuracyComparison.summarize(ComparisonMetric.HRV, days) + assertEquals(Verdict.CONSISTENTLY_HIGH, s.verdict) + assertNull(s.suggestedCorrection) + } + + @Test + fun stageAgreementSummarizesMinutes() { + val days = (0 until 3).map { + AccuracyCheckDayEntity("c", ComparisonMetric.SLEEP_STAGES.name, it.toLong(), pairs = 400, inBand = 300, computedAt = 0) + } + assertEquals(0.75, AccuracyComparison.summarize(ComparisonMetric.SLEEP_STAGES, days).stageAgreement!!, 1e-9) + } + + @Test + fun aPercentDiffAgainstAZeroReferenceIsNoDiff() { + assertNull(AccuracyComparison.diff(ComparisonMetric.STEPS, 100.0, 0.0)) + assertFalse(daily(ComparisonMetric.STEPS, 0, 100.0, 0.0).valid) + } + + @Test + fun bandsRoundTripAndDefaultsAreNotStored() { + val raw = AccuracyComparison.encodeBands(mapOf(ComparisonMetric.STEPS to 12.0, ComparisonMetric.HR_REST to ComparisonMetric.HR_REST.band)) + assertEquals("STEPS=12.0", raw) + assertEquals(mapOf(ComparisonMetric.STEPS to 12.0), AccuracyComparison.parseBands(raw)) + assertNull(AccuracyComparison.encodeBands(emptyMap())) + } + + // ── scorer helpers ── + + @Test + fun onlyWholeDaysInsideTheWindowAreDailyDays() { + val start = day0 + 14 * h + val end = day0 + 3 * 24 * h + 9 * h + val d0 = LocalDate.of(2026, 10, 1).toEpochDay() + assertEquals(listOf(d0 + 1, d0 + 2), AccuracyScorer.fullDaysIn(start, end, utc)) + assertEquals(listOf(d0), AccuracyScorer.fullDaysIn(day0, day0 + 24 * h, utc)) + } + + // ── report text ── + + @Test + fun theReadingSaysWhichWayAndHowSteady() { + val days = (0 until 6).map { daily(ComparisonMetric.STEPS, it.toLong(), 8_200.0, 10_000.0) } + val s = AccuracyComparison.summarize(ComparisonMetric.STEPS, days) + val text = AccuracyReportText.reading(s, "Health Sync") + assertTrue(text, text.contains("18 % fewer steps than Health Sync")) + assertTrue(text, text.contains("on 6 of 6 days")) + assertTrue(text, text.contains("A correction would help")) + } + + @Test + fun anInconsistentReadingRefusesACorrection() { + val ring = listOf(10_000.0, 6_000.0, 12_500.0, 7_000.0, 11_000.0, 6_500.0) + val s = AccuracyComparison.summarize(ComparisonMetric.STEPS, ring.mapIndexed { i, r -> daily(ComparisonMetric.STEPS, i.toLong(), r, 9_000.0) }) + assertTrue(AccuracyReportText.reading(s, "Fitbit").contains("A single correction can't fix that")) + } + + @Test + fun worstFirstOrdersByDistanceOutsideTheBand() { + val steps = AccuracyComparison.summarize(ComparisonMetric.STEPS, (0 until 4).map { daily(ComparisonMetric.STEPS, it.toLong(), 7_000.0, 10_000.0) }) + val sleep = AccuracyComparison.summarize(ComparisonMetric.SLEEP_ASLEEP, (0 until 4).map { daily(ComparisonMetric.SLEEP_ASLEEP, it.toLong(), 440.0, 400.0) }) + val ok = AccuracyComparison.summarize(ComparisonMetric.DISTANCE, (0 until 4).map { daily(ComparisonMetric.DISTANCE, it.toLong(), 5_000.0, 5_100.0) }) + assertEquals(listOf(ComparisonMetric.STEPS, ComparisonMetric.SLEEP_ASLEEP), AccuracyReportText.worstFirst(listOf(sleep, ok, steps)).map { it.metric }) + } + + @Test + fun clockTimesWrapAcrossMidnight() { + assertEquals("23:30", AccuracyReportText.clock(-30.0)) + assertEquals("07:05", AccuracyReportText.clock(425.0)) + } +} From a7a5209477d25d4405347be306893842859b795f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 16:11:35 +0000 Subject: [PATCH 7/9] Accuracy check Phase 4: corrections, applied at read time only 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. --- .../health/accuracy/AccuracyCorrections.kt | 188 ++++++++++++++++++ .../service/DailyCalorieEstimator.kt | 38 +++- .../pulseloop/ui/screens/AccuracyCheckUi.kt | 14 ++ .../pulseloop/ui/screens/AccuracyReportUi.kt | 136 ++++++++++++- .../pulseloop/ui/screens/ActivityScreen.kt | 1 + .../java/com/pulseloop/ui/screens/Screens.kt | 2 + .../com/pulseloop/ui/screens/SleepScreen.kt | 1 + .../com/pulseloop/ui/screens/TodayScreen.kt | 6 +- .../com/pulseloop/ui/viewmodels/ViewModels.kt | 106 +++++++--- .../accuracy/AccuracyCorrectionsTest.kt | 147 ++++++++++++++ 10 files changed, 607 insertions(+), 32 deletions(-) create mode 100644 app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt create mode 100644 app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt new file mode 100644 index 00000000..60226e48 --- /dev/null +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt @@ -0,0 +1,188 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.data.PulseLoopDatabase +import com.pulseloop.data.entity.AccuracyCheckEntity +import com.pulseloop.data.entity.AccuracyCorrectionEntity +import com.pulseloop.data.entity.DeviceEntity +import com.pulseloop.service.DailyCalorieEstimator +import kotlinx.coroutines.flow.Flow +import kotlinx.coroutines.flow.combine +import kotlinx.coroutines.flow.distinctUntilChanged +import kotlin.math.roundToInt + +/** + * The corrections in force for the paired ring (docs/accuracy-check-plan.md, "Corrections"), + * applied at read time only. Stored rows stay as the ring sent them — it re-sends its history on + * every sync, so a rewritten row wouldn't stay rewritten anyway — and switching a correction off + * puts every figure back. Nothing corrected reaches Health Connect: the exporters read the raw + * rows and never call this. + * + * Applied to everything shown while that ring is paired, history included. Stored data carries no + * ring id, so "this ring's readings" can't be told apart from an earlier ring's; the corrections + * follow the ring that is paired now, and a different ring starts with none. + */ +data class Corrections( + val deviceKey: String?, + val items: Map, + /** For the rest/active split of heart rate; see [heartRate]. */ + val age: Int? = null, +) { + val isEmpty: Boolean get() = items.isEmpty() + + fun has(m: ComparisonMetric): Boolean = m in items + + private fun scale(m: ComparisonMetric): Double = items[m]?.value ?: 1.0 + private fun offset(m: ComparisonMetric): Double = items[m]?.value ?: 0.0 + + fun steps(v: Int): Int = if (has(ComparisonMetric.STEPS)) (v * scale(ComparisonMetric.STEPS)).roundToInt() else v + fun distanceMeters(v: Double): Double = v * scale(ComparisonMetric.DISTANCE) + + /** + * A heart-rate reading. A single sample's context isn't known at read time, so the split + * between the at-rest and active offsets is the Flex-HR threshold — the same one + * [DailyCalorieEstimator] uses to decide which samples are exertion. + */ + fun heartRate(bpm: Double): Double { + if (!has(ComparisonMetric.HR_REST) && !has(ComparisonMetric.HR_ACTIVE)) return bpm + val active = bpm >= DailyCalorieEstimator.flexHR(age ?: DEFAULT_AGE) + val m = if (active && has(ComparisonMetric.HR_ACTIVE)) ComparisonMetric.HR_ACTIVE + else if (!active && has(ComparisonMetric.HR_REST)) ComparisonMetric.HR_REST + else if (has(ComparisonMetric.HR_REST)) ComparisonMetric.HR_REST else ComparisonMetric.HR_ACTIVE + return (bpm + offset(m)).coerceAtLeast(1.0) + } + + /** A resting figure: its own correction when one was fitted, else the at-rest heart-rate offset. */ + fun restingHr(bpm: Double): Double = when { + has(ComparisonMetric.RESTING_HR) -> bpm + offset(ComparisonMetric.RESTING_HR) + has(ComparisonMetric.HR_REST) -> bpm + offset(ComparisonMetric.HR_REST) + else -> bpm + } + + /** + * The resting-HR baseline behind the HR zones. The baseline is a percentile and the at-rest + * correction an offset, and an offset moves a percentile by exactly itself, so the adjusted + * baseline needs no recompute (plan, Corrections rule 6). + */ + fun baseline(bpm: Double): Double = restingHr(bpm) + + fun spo2(v: Double): Double = if (has(ComparisonMetric.SPO2)) (v + offset(ComparisonMetric.SPO2)).coerceIn(0.0, 100.0) else v + + fun asleepMinutes(v: Int): Int = + if (has(ComparisonMetric.SLEEP_ASLEEP)) (v + offset(ComparisonMetric.SLEEP_ASLEEP)).roundToInt().coerceAtLeast(0) else v + + /** A day's activity totals as shown: steps and distance corrected, the stored row untouched. */ + fun day(row: com.pulseloop.data.entity.ActivityDailyEntity): com.pulseloop.data.entity.ActivityDailyEntity = + if (!has(ComparisonMetric.STEPS) && !has(ComparisonMetric.DISTANCE)) row + else row.copy(steps = steps(row.steps), distanceMeters = distanceMeters(row.distanceMeters)) + + /** A night as shown: its time asleep corrected. Stage blocks are never corrected. */ + fun sleep(s: com.pulseloop.data.entity.SleepSessionEntity): com.pulseloop.data.entity.SleepSessionEntity = + if (!has(ComparisonMetric.SLEEP_ASLEEP)) s else s.copy(totalMinutes = asleepMinutes(s.totalMinutes)) + + /** "Steps ×1.18 · heart rate at rest −3.0 bpm" — the caption a corrected screen carries. */ + fun describe(only: Set? = null): String? = items.values + .mapNotNull { c -> ComparisonMetric.byName(c.metric)?.let { it to c } } + .filter { (m, _) -> only == null || m in only } + .sortedBy { it.first.ordinal } + .joinToString(" · ") { (m, c) -> "${m.label.lowercase()} ${AccuracyCorrections.formatValue(m, c.value)}" } + .ifEmpty { null } + + companion object { + const val DEFAULT_AGE = 35 + val NONE = Corrections(null, emptyMap()) + } +} + +object AccuracyCorrections { + + /** A correction older than this, or fitted on other firmware, is flagged for a re-check. */ + const val STALE_MS = 90L * 86_400_000L + + val CALORIE_INPUTS = setOf(ComparisonMetric.STEPS, ComparisonMetric.HR_REST, ComparisonMetric.HR_ACTIVE) + + fun formatValue(m: ComparisonMetric, v: Double): String = when (m.correction) { + CorrectionKind.SCALE -> "×%.2f".format(v) + CorrectionKind.OFFSET -> AccuracyReportText.signed(m, v) + null -> v.toString() + } + + fun of(device: DeviceEntity?, all: List, age: Int?): Corrections { + val d = device?.takeIf { it.id != RingIdentity.DEMO_DEVICE_ID } ?: return Corrections.NONE + val key = RingIdentity.keyOf(d) + val items = all.filter { it.deviceKey == key && it.enabled } + .mapNotNull { c -> ComparisonMetric.byName(c.metric)?.let { it to c } } + .toMap() + return Corrections(key, items, age) + } + + suspend fun load(db: PulseLoopDatabase): Corrections = runCatching { + of(db.deviceDao().currentReal(), db.accuracyDao().allCorrections(), db.userProfileDao().get()?.age) + }.getOrDefault(Corrections.NONE) + + fun flow(db: PulseLoopDatabase): Flow = + combine(db.deviceDao().currentFlow(), db.accuracyDao().allCorrectionsFlow()) { d, all -> + of(d, all, null) + }.distinctUntilChanged() + + fun isStale(c: AccuracyCorrectionEntity, device: DeviceEntity?, now: Long = System.currentTimeMillis()): Boolean = + now - c.createdAt > STALE_MS || + (c.firmware != null && device?.firmwareVersion != null && device.firmwareVersion != c.firmware) + + /** + * Saves a correction for the check's ring, from the check's fitted suggestion or the value the + * user moved it to. Only for the ring that is paired now: a correction fitted on another ring + * would be invented data for this one. + */ + suspend fun accept( + db: PulseLoopDatabase, + check: AccuracyCheckEntity, + summary: AccuracyComparison.Summary, + value: Double, + now: Long = System.currentTimeMillis(), + ): Boolean { + val kind = summary.metric.correction ?: return false + val fitted = summary.suggestedCorrection ?: return false + val ring = db.deviceDao().currentReal() ?: return false + if (RingIdentity.keyOf(ring) != check.deviceKey) return false + val existing = db.accuracyDao().corrections(check.deviceKey).firstOrNull { it.metric == summary.metric.name } + db.accuracyDao().upsertCorrection( + AccuracyCorrectionEntity( + deviceKey = check.deviceKey, + metric = summary.metric.name, + kind = if (kind == CorrectionKind.SCALE) AccuracyCorrectionEntity.KIND_SCALE else AccuracyCorrectionEntity.KIND_OFFSET, + value = value, + fittedValue = fitted, + fromCheckId = check.id, + enabled = true, + firmware = check.firmware ?: ring.firmwareVersion, + createdAt = existing?.createdAt?.takeIf { existing.fromCheckId == check.id } ?: now, + updatedAt = now, + ), + ) + if (summary.metric in CALORIE_INPUTS) recomputeAdjustedCalories(db) + return true + } + + suspend fun setEnabled(db: PulseLoopDatabase, c: AccuracyCorrectionEntity, enabled: Boolean) { + db.accuracyDao().upsertCorrection(c.copy(enabled = enabled, updatedAt = System.currentTimeMillis())) + if (ComparisonMetric.byName(c.metric) in CALORIE_INPUTS) recomputeAdjustedCalories(db) + } + + suspend fun remove(db: PulseLoopDatabase, c: AccuracyCorrectionEntity) { + db.accuracyDao().deleteCorrection(c.deviceKey, c.metric) + if (ComparisonMetric.byName(c.metric) in CALORIE_INPUTS) recomputeAdjustedCalories(db) + } + + /** + * Re-runs the calorie estimate over recent days, so the corrected copy follows the + * corrections exactly and switching them off restores it (Corrections rule 6). The raw + * estimate — what Health Connect gets — is recomputed alongside from the same inputs and + * comes out unchanged. + */ + suspend fun recomputeAdjustedCalories(db: PulseLoopDatabase, days: Int = 90) { + val profile = db.userProfileDao().get()?.let { DailyCalorieEstimator.profileOf(it) } ?: return + db.activityDailyDao().recentReal(days).forEach { day -> + runCatching { DailyCalorieEstimator.recompute(day.date, db, profile, touchUpdatedAt = false) } + } + } +} diff --git a/app/src/main/java/com/pulseloop/service/DailyCalorieEstimator.kt b/app/src/main/java/com/pulseloop/service/DailyCalorieEstimator.kt index 1d80cadf..900a56ce 100644 --- a/app/src/main/java/com/pulseloop/service/DailyCalorieEstimator.kt +++ b/app/src/main/java/com/pulseloop/service/DailyCalorieEstimator.kt @@ -137,6 +137,24 @@ object DailyCalorieEstimator { fun effectiveActiveCalories(day: ActivityDailyEntity): Double? = deviceReportedCalories(day) ?: day.estimatedActiveCalories + /** + * What the app shows: [effectiveActiveCalories], but with the accuracy-corrected estimate when + * there is one. Never for export — Health Connect reads the raw column. + */ + fun displayActiveCalories(day: ActivityDailyEntity): Double? = + deviceReportedCalories(day) ?: day.estimatedActiveCaloriesAdjusted ?: day.estimatedActiveCalories + + /** [effectiveCalories] for display, on [displayActiveCalories]. */ + fun displayCalories( + day: ActivityDailyEntity, + profile: Profile, + now: Long = System.currentTimeMillis(), + ): Double? { + deviceReportedCalories(day)?.let { return it } + val active = day.estimatedActiveCaloriesAdjusted ?: day.estimatedActiveCalories ?: return null + return bmrPerMinute(profile) * elapsedMinutes(day.date, now) + active + } + /** Minutes of [dayStart] that have elapsed: partial for today, full for the past, 0 ahead. */ private fun elapsedMinutes(dayStart: Long, now: Long): Double = when { now < dayStart -> 0.0 @@ -153,7 +171,7 @@ object DailyCalorieEstimator { * to estimate against, and inserting a row here would fabricate a zero-step `ring_history` day * in the history and charts (iOS: `guard let row = MetricsRepository.activity(...) else return`). */ - suspend fun recompute(dayStart: Long, db: PulseLoopDatabase, profile: Profile) { + suspend fun recompute(dayStart: Long, db: PulseLoopDatabase, profile: Profile, touchUpdatedAt: Boolean = true) { val row = db.activityDailyDao().byDay(dayStart) ?: return val dayEnd = dayStart + DAY_MS @@ -176,9 +194,25 @@ object DailyCalorieEstimator { hrSamples = hrSamples, profile = profile, ) + // The same estimate from the ring's inputs with its accuracy corrections applied + // (docs/accuracy-check-plan.md, Corrections rule 6). Kept in its own column: the app shows + // it, Health Connect gets `estimatedActiveCalories`, which stays raw. + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val adjusted = if (corrections.items.keys.none { it in com.pulseloop.health.accuracy.AccuracyCorrections.CALORIE_INPUTS }) null + else estimateNetActive( + dayStart = dayStart, + dayTotalSteps = corrections.steps(row.steps), + buckets = buckets.map { it.copy(steps = corrections.steps(it.steps)) }, + workouts = workouts, + hrSamples = hrSamples.map { it.copy(value = corrections.heartRate(it.value)) }, + profile = profile, + ) db.activityDailyDao().upsert(row.copy( estimatedActiveCalories = active, - updatedAt = System.currentTimeMillis(), + estimatedActiveCaloriesAdjusted = adjusted, + // A correction change only moves the adjusted copy, which nothing exports; leaving + // updatedAt alone keeps the Health Connect export from re-reading 90 days for it. + updatedAt = if (touchUpdatedAt || active != row.estimatedActiveCalories) System.currentTimeMillis() else row.updatedAt, )) } diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt index f3456296..c73afb0e 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt @@ -190,6 +190,8 @@ fun AccuracyCheckSettingsScreen(onBack: () -> Unit) { } } + if (hasRing) AccuracyCorrectionsCard() + val past = history.filter { it.state == AccuracyCheckEntity.STATE_DONE } if (past.isNotEmpty()) { AccuracyCard { @@ -413,6 +415,18 @@ internal fun AccuracyCard(content: @Composable () -> Unit) { ) { content() } } +/** + * The caption a screen carries while it shows accuracy-corrected figures (plan, Corrections rule + * 4: labelled wherever shown). [note] is [com.pulseloop.health.accuracy.Corrections.describe]. + */ +@Composable +internal fun AdjustedCaption(note: String) { + Text( + "Adjusted by your accuracy check: $note. Settings → Accuracy check to change.", + fontSize = 11.sp, color = PulseColors.textMuted, + ) +} + /** Today's one-line banner while a check is open. */ @Composable internal fun AccuracyCheckBanner(c: AccuracyCheckEntity, onOpen: () -> Unit) { diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt index 9c8284c9..274663c1 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt @@ -9,8 +9,11 @@ import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.layout.padding import androidx.compose.foundation.layout.size import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.material3.AlertDialog +import androidx.compose.material3.Button import androidx.compose.material3.CircularProgressIndicator import androidx.compose.material3.Slider +import androidx.compose.material3.Switch import androidx.compose.material3.Text import androidx.compose.material3.TextButton import androidx.compose.runtime.Composable @@ -34,6 +37,8 @@ import com.pulseloop.data.entity.AccuracyCheckDayEntity import com.pulseloop.data.entity.AccuracyCheckEntity import com.pulseloop.health.accuracy.AccuracyComparison import com.pulseloop.health.accuracy.AccuracyComparison.Verdict +import com.pulseloop.health.accuracy.AccuracyCorrections +import com.pulseloop.health.accuracy.RingIdentity import com.pulseloop.health.accuracy.AccuracyReportText import com.pulseloop.health.accuracy.AccuracyScorer import com.pulseloop.health.accuracy.ComparisonMetric @@ -268,7 +273,136 @@ private fun StageConfusion(days: List, ref: String) { } } -/** Filled in by the corrections phase; shows nothing until then. */ +/** + * Under a metric with a consistent bias: apply the fitted correction, adjust it, or switch it off + * (plan, "Corrections"). Only for the ring the check was run on, and only while it is paired. + */ @Composable internal fun AccuracyCorrectionControl(check: AccuracyCheckEntity, summary: AccuracyComparison.Summary) { + val metric = summary.metric + val fitted = summary.suggestedCorrection ?: return + val context = LocalContext.current + val scope = rememberCoroutineScope() + val db = remember { PulseLoopDatabase.getInstance(context) } + val all by db.accuracyDao().allCorrectionsFlow().collectAsState(initial = emptyList()) + val ring by db.deviceDao().currentFlow().collectAsState(initial = null) + val existing = all.firstOrNull { it.deviceKey == check.deviceKey && it.metric == metric.name } + var editing by remember { mutableStateOf(false) } + val paired = ring?.let { it.id != RingIdentity.DEMO_DEVICE_ID && RingIdentity.keyOf(it) == check.deviceKey } == true + + if (!paired) { + Text("This check was run on ${check.deviceLabel}. Pair that ring to apply a correction from it.", fontSize = 12.sp, color = PulseColors.textMuted) + return + } + when { + existing != null && existing.enabled -> Row(verticalAlignment = Alignment.CenterVertically) { + Text("Correction on: ${AccuracyCorrections.formatValue(metric, existing.value)}", fontSize = 12.sp, + color = PulseColors.success, modifier = Modifier.weight(1f)) + TextButton(onClick = { editing = true }) { Text("Change") } + TextButton(onClick = { scope.launch { AccuracyCorrections.setEnabled(db, existing, false) } }) { Text("Turn off") } + } + existing != null -> Row(verticalAlignment = Alignment.CenterVertically) { + Text("Correction off (${AccuracyCorrections.formatValue(metric, existing.value)})", fontSize = 12.sp, + color = PulseColors.textMuted, modifier = Modifier.weight(1f)) + TextButton(onClick = { scope.launch { AccuracyCorrections.setEnabled(db, existing, true) } }) { Text("Turn on") } + } + else -> Button(onClick = { editing = true }, modifier = Modifier.fillMaxWidth()) { + Text("Apply correction (${AccuracyCorrections.formatValue(metric, fitted)})") + } + } + if (editing) { + CorrectionDialog(metric, fitted, existing?.value ?: fitted, check.referenceLabel, onDismiss = { editing = false }) { value -> + editing = false + scope.launch { AccuracyCorrections.accept(db, check, summary, value) } + } + } +} + +@Composable +private fun CorrectionDialog( + metric: ComparisonMetric, + fitted: Double, + start: Double, + ref: String, + onDismiss: () -> Unit, + onSave: (Double) -> Unit, +) { + val range = correctionRange(metric, fitted) + var value by remember { mutableStateOf(start.coerceIn(range.start.toDouble(), range.endInclusive.toDouble())) } + AlertDialog( + onDismissRequest = onDismiss, + title = { Text("Correct ${metric.label.lowercase()}") }, + text = { + Column(verticalArrangement = Arrangement.spacedBy(8.dp)) { + Text( + "Fitted from this check so your ring matches $ref: ${AccuracyCorrections.formatValue(metric, fitted)}. " + + "It changes what PulseLoop shows and what it works out from it (zones, resting baseline, calorie estimate). " + + "Your ring's stored readings and what goes to Health Connect stay as measured.", + fontSize = 12.sp, + ) + Text(AccuracyCorrections.formatValue(metric, value), fontSize = 20.sp, fontWeight = FontWeight.Bold) + Slider(value = value.toFloat(), onValueChange = { value = it.toDouble() }, valueRange = range) + TextButton(onClick = { value = fitted }) { Text("Use the fitted value") } + } + }, + confirmButton = { TextButton(onClick = { onSave(roundCorrection(metric, value)) }) { Text("Apply") } }, + dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }, + ) +} + +private fun correctionRange(m: ComparisonMetric, fitted: Double): ClosedFloatingPointRange = when (m.correction) { + com.pulseloop.health.accuracy.CorrectionKind.SCALE -> + (minOf(fitted, 1.0) * 0.8).coerceAtLeast(0.5).toFloat()..(maxOf(fitted, 1.0) * 1.2).coerceAtMost(2.5).toFloat() + else -> { + val span = maxOf(kotlin.math.abs(fitted) * 2, when (m) { + ComparisonMetric.SLEEP_ASLEEP -> 60.0 + ComparisonMetric.SPO2 -> 4.0 + else -> 10.0 + }) + (-span).toFloat()..span.toFloat() + } +} + +private fun roundCorrection(m: ComparisonMetric, v: Double): Double = when (m.correction) { + com.pulseloop.health.accuracy.CorrectionKind.SCALE -> (v * 100).roundToInt() / 100.0 + else -> if (m == ComparisonMetric.SLEEP_ASLEEP) v.roundToInt().toDouble() else (v * 2).roundToInt() / 2.0 +} + +/** The paired ring's corrections, on the accuracy-check screen: switch, stale flag, remove. */ +@Composable +internal fun AccuracyCorrectionsCard() { + val context = LocalContext.current + val scope = rememberCoroutineScope() + val db = remember { PulseLoopDatabase.getInstance(context) } + val all by db.accuracyDao().allCorrectionsFlow().collectAsState(initial = emptyList()) + val ring by db.deviceDao().currentFlow().collectAsState(initial = null) + val r = ring?.takeIf { it.id != RingIdentity.DEMO_DEVICE_ID } ?: return + val key = RingIdentity.keyOf(r) + val mine = all.filter { it.deviceKey == key }.sortedBy { ComparisonMetric.byName(it.metric)?.ordinal ?: 99 } + AccuracyCard { + Text("Corrections for ${RingIdentity.labelOf(r)}", fontSize = 15.sp, fontWeight = FontWeight.Bold, color = PulseColors.textPrimary) + if (mine.isEmpty()) { + Text( + if (all.isNotEmpty()) "No accuracy check for this ring yet. Corrections from another ring don't carry over." + else "None. A finished check offers one wherever the ring is consistently off.", + fontSize = 12.sp, color = PulseColors.textMuted, + ) + return@AccuracyCard + } + mine.forEach { c -> + val m = ComparisonMetric.byName(c.metric) ?: return@forEach + Row(verticalAlignment = Alignment.CenterVertically) { + Column(Modifier.weight(1f)) { + Text("${m.label}: ${AccuracyCorrections.formatValue(m, c.value)}", fontSize = 13.sp, color = PulseColors.textPrimary) + if (AccuracyCorrections.isStale(c, r)) { + Text("Fitted ${AccuracyUiText.date(c.createdAt)}${if (c.firmware != null && c.firmware != r.firmwareVersion) " on other firmware" else ""}: worth a fresh check.", + fontSize = 11.sp, color = PulseColors.warning) + } + } + Switch(checked = c.enabled, onCheckedChange = { on -> scope.launch { AccuracyCorrections.setEnabled(db, c, on) } }) + TextButton(onClick = { scope.launch { AccuracyCorrections.remove(db, c) } }) { Text("Remove") } + } + } + Text("Applied to what PulseLoop shows, never to stored readings or Health Connect.", fontSize = 11.sp, color = PulseColors.textMuted) + } } diff --git a/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt index c5479be6..524d093f 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt @@ -158,6 +158,7 @@ fun ActivityScreen( // Day navigation (issue #76): the summary + RECORDS cards follow the shown day, so a // past day's steps/distance/calories are reachable the way Sleep already allows. item { ActivityDayNavHeader(state, viewModel) } + state.adjustedNote?.let { note -> item { AdjustedCaption(note) } } item { DailyActivitySummaryCard(state, units) } diff --git a/app/src/main/java/com/pulseloop/ui/screens/Screens.kt b/app/src/main/java/com/pulseloop/ui/screens/Screens.kt index 12ca5d04..4f54bbdc 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/Screens.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/Screens.kt @@ -287,6 +287,7 @@ fun VitalsScreen( Column(Modifier.weight(1f)) { Text("Vitals", style = MaterialTheme.typography.headlineLarge, fontWeight = FontWeight.Bold) Text("Live measurements and trends", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant) + state.adjustedNote?.let { AdjustedCaption(it) } } // Measure button: combined (0x23) for 56ff/Jring, or sequential live // HR + SpO₂ (0x69) for Colmi. Hidden for rings that support neither. @@ -697,6 +698,7 @@ fun VitalDetailScreen( item { PeriodSegmentedControl(selected = state.period, onSelect = { vm.setPeriod(it) }) } + state.adjustedNote?.let { note -> item { AdjustedCaption(note) } } // 2. Chart card: unit label + interactive trend chart (24dp continuous corners). item { diff --git a/app/src/main/java/com/pulseloop/ui/screens/SleepScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/SleepScreen.kt index d54de1ea..700d5b4d 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/SleepScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/SleepScreen.kt @@ -105,6 +105,7 @@ fun SleepScreen( item { SleepRangeSelector(state.range) { viewModel?.setRange(it) } } + state.adjustedNote?.let { note -> item { AdjustedCaption(note) } } if (state.range == SleepRangeKey.DAY) dayItems(state, navController, viewModel) else aggregateItems(state, navController) item { Spacer(Modifier.height(64.dp)) } diff --git a/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt index 6ae2195b..f60a5ba6 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/TodayScreen.kt @@ -120,7 +120,10 @@ fun TodayScreen( val mealsToday = food?.meals // Ring steps calibrated against the phone, only when the user applied it in My Health. val stepFactor by produceState(null, state.lastUpdated) { - value = if (!com.pulseloop.service.StepCalibration.isApplied(context)) null else runCatching { + // An accuracy-check steps correction supersedes the phone factor: applying both would + // correct the same undercount twice. + val accuracySteps = com.pulseloop.health.accuracy.AccuracyCorrections.load(db).has(com.pulseloop.health.accuracy.ComparisonMetric.STEPS) + value = if (accuracySteps || !com.pulseloop.service.StepCalibration.isApplied(context)) null else runCatching { val zone = java.time.ZoneId.systemDefault() val ring = db.activityDailyDao().recentReal(60).associate { java.time.Instant.ofEpochMilli(it.date).atZone(zone).toLocalDate() to it.steps } com.pulseloop.service.StepCalibration.factor(com.pulseloop.service.StepCalibration.phoneDays(context), ring, java.time.LocalDate.now())?.factor @@ -219,6 +222,7 @@ fun TodayScreen( // Accuracy check in progress (docs/accuracy-check-plan.md): say so, since it pauses export. accuracyOpen?.let { c -> item { AccuracyCheckBanner(c) { navController?.navigate("settings/accuracy-check") } } } + state.adjustedNote?.let { note -> item { AdjustedCaption(note) } } // Glance: one line of what today means, and an alert line only when something is off. item { diff --git a/app/src/main/java/com/pulseloop/ui/viewmodels/ViewModels.kt b/app/src/main/java/com/pulseloop/ui/viewmodels/ViewModels.kt index d3eb8366..0658f88f 100644 --- a/app/src/main/java/com/pulseloop/ui/viewmodels/ViewModels.kt +++ b/app/src/main/java/com/pulseloop/ui/viewmodels/ViewModels.kt @@ -8,6 +8,7 @@ import com.pulseloop.data.PulseLoopDatabase import com.pulseloop.data.dao.Bucket import com.pulseloop.data.dao.MeasurementDeletionDao import com.pulseloop.data.entity.* +import com.pulseloop.health.accuracy.AccuracyCorrections import com.pulseloop.ring.* import com.pulseloop.coach.summaries.CoachSummaryKind import com.pulseloop.service.DailyCalorieEstimator @@ -72,6 +73,8 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore val steps7d: List = emptyList(), /** Latest "today" coach summary card, when the coach has generated one. */ val coachSummary: CoachSummaryEntity? = null, + /** The accuracy corrections applied to this screen's figures, for its caption; null = none. */ + val adjustedNote: String? = null, ) private val _state = MutableStateFlow(TodayState()) @@ -84,14 +87,19 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore init { viewModelScope.launch { - currentDayValues(todayStart, db.activityDailyDao()::byDayFlow).collect { activity -> + currentDayValues(todayStart, db.activityDailyDao()::byDayFlow) + .combine(AccuracyCorrections.flow(db)) { activity, _ -> activity } + .collect { raw -> + // Accuracy corrections are read-time only (docs/accuracy-check-plan.md). + val corrections = AccuracyCorrections.load(db) + val activity = raw?.let(corrections::day) // iOS #98: the ring's own calorie figure wins when it reported one; otherwise show // the on-device estimate (BMR accrued so far + net active). Reading `calories` // straight off the row would show 0 all day for rings that report none — which is // the whole reason the estimator exists. val profile = db.userProfileDao().get()?.let { DailyCalorieEstimator.profileOf(it) } val calories = activity?.let { row -> - profile?.let { DailyCalorieEstimator.effectiveCalories(row, it) } + profile?.let { DailyCalorieEstimator.displayCalories(row, it) } ?: DailyCalorieEstimator.deviceReportedCalories(row) } _state.update { it.copy( @@ -99,6 +107,7 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore calories = calories, distanceMeters = activity?.distanceMeters, activeMinutes = activity?.activeMinutes, + adjustedNote = corrections.describe(), ) } } } @@ -117,8 +126,8 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore } // 7-day step series for the hero delta (oldest→newest; DAO returns newest-first). viewModelScope.launch { - db.activityDailyDao().recentFlow(7).collect { days -> - _state.update { it.copy(steps7d = days.reversed().map { d -> d.steps }) } + db.activityDailyDao().recentFlow(7).combine(AccuracyCorrections.flow(db)) { days, c -> days to c }.collect { (days, c) -> + _state.update { it.copy(steps7d = days.reversed().map { d -> c.steps(d.steps) }) } } } // Today's coach summary card (kind="today", scopeKey=local date). @@ -145,10 +154,11 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore while (true) { try { val nowMs = System.currentTimeMillis() - val hr = db.measurementDao().latest(MeasurementKind.HEART_RATE.name) + val corrections = AccuracyCorrections.load(db) + val hr = db.measurementDao().latest(MeasurementKind.HEART_RATE.name)?.let(corrections::heartRate) val samples = db.measurementDao() .range(MeasurementKind.HEART_RATE.name, nowMs - 24 * 3600_000L, nowMs) - .map { it.value } + .map { corrections.heartRate(it.value) } val resting = com.pulseloop.service.HeartRateZones.restingHeartRate(samples) _state.update { it.copy(heartRate = hr?.toInt(), restingHR = resting, lastUpdated = nowMs) } } catch (_: Exception) {} @@ -159,7 +169,7 @@ class TodayViewModel(db: PulseLoopDatabase, private val apiKeyStore: ApiKeyStore viewModelScope.launch { while (true) { try { - val spo2 = db.measurementDao().latest(MeasurementKind.SPO2.name) + val spo2 = db.measurementDao().latest(MeasurementKind.SPO2.name)?.let(AccuracyCorrections.load(db)::spo2) _state.update { it.copy(spo2 = spo2?.toInt(), lastUpdated = System.currentTimeMillis()) } } catch (_: Exception) {} kotlinx.coroutines.delay(2000) @@ -237,6 +247,8 @@ class SleepViewModel( // LLM summaries when present (fallback = the scripted coach above) val daySummary: CoachSummaryEntity? = null, val rangeSummary: CoachSummaryEntity? = null, + /** Accuracy corrections applied to the time-asleep figures; null = none. */ + val adjustedNote: String? = null, ) private val _state = MutableStateFlow(SleepState()) @@ -255,8 +267,8 @@ class SleepViewModel( init { // Any sleep-table change retriggers a rebuild of the selected range. viewModelScope.launch { - db.sleepSessionDao().recentFlow(7).collect { sessions -> - _state.update { it.copy(recentSessions = sessions) } + db.sleepSessionDao().recentFlow(7).combine(AccuracyCorrections.flow(db)) { sessions, c -> sessions to c }.collect { (sessions, c) -> + _state.update { it.copy(recentSessions = sessions.map(c::sleep)) } try { rebuild(_state.value.range) } catch (_: Exception) {} } } @@ -272,7 +284,9 @@ class SleepViewModel( // ── Today tile (never moves with Day-view navigation) ── val todayReference = TimeUtil.referenceNightLocal() - val night = db.sleepSessionDao().byDay(todayReference)?.takeIf { it.totalMinutes > 0 } + // Time asleep as corrected by an accuracy check, read-time only; stages stay as the ring sent them. + val corrections = AccuracyCorrections.load(db) + val night = db.sleepSessionDao().byDay(todayReference)?.takeIf { it.totalMinutes > 0 }?.let(corrections::sleep) val nightBlocks = night?.let { blocksFor(it.id) } ?: emptyList() val scoreResult = night?.let { SleepScore.calculate(it, nightBlocks, goal ?: 480) } @@ -285,7 +299,7 @@ class SleepViewModel( // afterwards. Real wins (`DemoDataPolicy`). val shownAll = db.sleepSessionDao().allByDay(shownReference).filter { it.totalMinutes > 0 } val shownRing = shownAll.filterNot { DemoDataPolicy.isDemo(it.sourceRaw) } - val daySessions = (if (shownRing.isNotEmpty()) shownRing else shownAll).sortedBy { it.startAt } + val daySessions = (if (shownRing.isNotEmpty()) shownRing else shownAll).sortedBy { it.startAt }.map(corrections::sleep) val dayBlocks = daySessions.associate { it.id to blocksFor(it.id) } // The primary (longest) session drives the scripted day-level coach fallback. val primary = daySessions.maxByOrNull { it.totalMinutes } @@ -319,7 +333,7 @@ class SleepViewModel( // Collapse each waking day (main night + naps) into one combined summary so a night plus // naps counts as ONE tracked night, consistent with the "N of M nights" hero and averages. val collapsed = SleepInsights.collapseByDay(sessions, realLookup) - val collapsedSessions = collapsed.map { it.session } + val collapsedSessions = collapsed.map { corrections.sleep(it.session) } val collapsedBlocks = collapsed.associate { it.session.id to it.blocks } val lookup: (String) -> List = { collapsedBlocks[it] ?: emptyList() } val valid = SleepInsights.validSessions(collapsedSessions) @@ -363,6 +377,7 @@ class SleepViewModel( goalMinutes = goal, daySummary = daySummary, rangeSummary = rangeSummary, + adjustedNote = corrections.describe(setOf(com.pulseloop.health.accuracy.ComparisonMetric.SLEEP_ASLEEP)), ) } } @@ -460,6 +475,8 @@ class ActivityViewModel(db: PulseLoopDatabase) : ViewModel() { val caloriesGoal: Int = UserGoalEntity.DEFAULT_CALORIES, val sleepMinutesGoal: Int = 480, val workoutsPerWeekGoal: Int = 4, + /** Accuracy corrections applied to steps and distance; null = none. */ + val adjustedNote: String? = null, ) private val _state = MutableStateFlow(ActivityState()) @@ -481,23 +498,29 @@ class ActivityViewModel(db: PulseLoopDatabase) : ViewModel() { init { viewModelScope.launch { - db.activityDailyDao().recentFlow(7).collect { days -> - _state.update { it.copy(recentDays = days) } + db.activityDailyDao().recentFlow(7).combine(AccuracyCorrections.flow(db)) { days, c -> days to c }.collect { (days, c) -> + _state.update { it.copy(recentDays = days.map(c::day)) } } } viewModelScope.launch { - currentDayValues(todayStart, db.activityDailyDao()::byDayFlow).collect { day -> - _state.update { it.copy(today = day) } - } + currentDayValues(todayStart, db.activityDailyDao()::byDayFlow) + .combine(AccuracyCorrections.flow(db)) { day, c -> day?.let(c::day) to c } + .collect { (day, c) -> + _state.update { it.copy(today = day, adjustedNote = c.describe(setOf( + com.pulseloop.health.accuracy.ComparisonMetric.STEPS, com.pulseloop.health.accuracy.ComparisonMetric.DISTANCE, + ))) } + } } viewModelScope.launch { - shownDayStart.flatMapLatest { day -> db.activityDailyDao().byDayFlow(day) }.collect { day -> + shownDayStart.flatMapLatest { day -> db.activityDailyDao().byDayFlow(day) } + .combine(AccuracyCorrections.flow(db)) { day, c -> day?.let(c::day) } + .collect { day -> val profile = db.userProfileDao().get()?.let { DailyCalorieEstimator.profileOf(it) } val calories = day?.let { row -> - profile?.let { DailyCalorieEstimator.effectiveCalories(row, it) } + profile?.let { DailyCalorieEstimator.displayCalories(row, it) } ?: DailyCalorieEstimator.deviceReportedCalories(row) } - val activeCalories = day?.let { DailyCalorieEstimator.effectiveActiveCalories(it) } + val activeCalories = day?.let { DailyCalorieEstimator.displayActiveCalories(it) } _state.update { it.copy(daySummary = day, dayCalories = calories, dayActiveCalories = activeCalories) } } } @@ -658,6 +681,8 @@ class VitalsViewModel(private val db: PulseLoopDatabase, private val apiKeyStore val supportsGlucose: Boolean = false, val supportsManualHr: Boolean = false, val supportsManualSpo2: Boolean = false, + /** Accuracy corrections applied to heart rate and SpO₂ here; null = none. */ + val adjustedNote: String? = null, ) private val _state = MutableStateFlow(VitalsState()) @@ -727,8 +752,11 @@ class VitalsViewModel(private val db: PulseLoopDatabase, private val apiKeyStore else -> emptyList() } - val hr = series(MeasurementKind.HEART_RATE) - val spo2 = series(MeasurementKind.SPO2) + // Accuracy corrections (docs/accuracy-check-plan.md) are applied here, at read time, so the + // cards, charts, widgets and zones built from this state all see the same figures. + val corrections = AccuracyCorrections.load(db) + val hr = series(MeasurementKind.HEART_RATE).map { it.copy(value = corrections.heartRate(it.value)) } + val spo2 = series(MeasurementKind.SPO2).map { it.copy(value = corrections.spo2(it.value)) } val hrv = if (caps.contains(WearableCapability.HRV)) series(MeasurementKind.HRV) else emptyList() val stress = if (caps.contains(WearableCapability.STRESS)) series(MeasurementKind.STRESS) else emptyList() val fatigue = if (caps.contains(WearableCapability.FATIGUE)) series(MeasurementKind.FATIGUE) else emptyList() @@ -820,7 +848,7 @@ class VitalsViewModel(private val db: PulseLoopDatabase, private val apiKeyStore bpDiaSeries = bpDia.map { VitalSample(it.timestamp, it.value) }, glucoseSeries = gluc.map { VitalSample(it.timestamp, it.value + glucoseOffset) }, peakHr = hr.maxOfOrNull { it.value }, - profile = apiKeyStore.physiologyProfile(userProfile), + profile = apiKeyStore.physiologyProfile(userProfile, corrections), // "Reference entered" ⇔ a non-zero calibration offset in Settings (0 = not set). hasBPReference = (apiKeyStore?.bpAdjustSystolic ?: 0) != 0 || (apiKeyStore?.bpAdjustDiastolic ?: 0) != 0, isGlucoseCalibrated = glucoseOffset != 0.0 || (apiKeyStore?.glucoseRefMgdl ?: 0.0) != 0.0, @@ -832,6 +860,10 @@ class VitalsViewModel(private val db: PulseLoopDatabase, private val apiKeyStore supportsGlucose = caps.contains(WearableCapability.BLOOD_SUGAR), supportsManualHr = caps.contains(WearableCapability.MANUAL_HEART_RATE), supportsManualSpo2 = caps.contains(WearableCapability.MANUAL_SPO2), + adjustedNote = corrections.describe(setOf( + com.pulseloop.health.accuracy.ComparisonMetric.HR_REST, com.pulseloop.health.accuracy.ComparisonMetric.HR_ACTIVE, + com.pulseloop.health.accuracy.ComparisonMetric.SPO2, com.pulseloop.health.accuracy.ComparisonMetric.RESTING_HR, + )), ) } @@ -848,7 +880,10 @@ class VitalsViewModel(private val db: PulseLoopDatabase, private val apiKeyStore * with it — dropping them here left [VitalsThresholdEngine] with a null baseline and no way to see * the user's chosen mode or custom boundaries, so every zone computation took the default branch. */ -private fun ApiKeyStore?.physiologyProfile(profile: UserProfileEntity?): UserPhysiologyProfile = +private fun ApiKeyStore?.physiologyProfile( + profile: UserProfileEntity?, + corrections: com.pulseloop.health.accuracy.Corrections = com.pulseloop.health.accuracy.Corrections.NONE, +): UserPhysiologyProfile = UserPhysiologyProfile.fromProfile( profile?.age, profile?.sex, athleteMode = this?.athleteMode ?: false, @@ -857,7 +892,9 @@ private fun ApiKeyStore?.physiologyProfile(profile: UserProfileEntity?): UserPhy hasKnownLungCondition = this?.hasKnownLungCondition == true, preferredGlucoseUnit = this?.preferredGlucoseUnit ?: com.pulseloop.service.GlucoseUnit.MGDL, hrZoneModeRaw = profile?.hrZoneModeRaw ?: "auto", - hrRestingBaseline = profile?.hrRestingBaseline, + // The zones follow the corrected heart rate, so the baseline they sit on is corrected too + // (plan, Corrections rule 6); the stored baseline, which Health Connect gets, stays raw. + hrRestingBaseline = profile?.hrRestingBaseline?.let(corrections::baseline), hrCustomLowUpper = profile?.hrCustomLowUpper, hrCustomAthleticUpper = profile?.hrCustomAthleticUpper, hrCustomElevatedStart = profile?.hrCustomElevatedStart, @@ -1143,6 +1180,8 @@ class VitalDetailViewModel( val isDerived: Boolean = false, /** The user's own 30-day usual range in display units, drawn as a band (service/UsualRange). */ val usualRange: ClosedFloatingPointRange? = null, + /** Accuracy correction applied to this metric's readings; null = none. */ + val adjustedNote: String? = null, ) /** @@ -1179,7 +1218,7 @@ class VitalDetailViewModel( viewModelScope.launch { try { val userProfile = db.userProfileDao().get() - val physiology = apiKeyStore.physiologyProfile(userProfile) + val physiology = apiKeyStore.physiologyProfile(userProfile, AccuracyCorrections.load(db)) engineThresholds(metric, physiology)?.let { engine -> _state.update { it.copy(thresholds = engine) } } @@ -1272,11 +1311,12 @@ class VitalDetailViewModel( val prevEnd = if (now < windowEnd) minOf(windowStart, prevStart + (now - windowStart)) else windowStart val dao = db.measurementDao() + val corrections = AccuracyCorrections.load(db) // Profile-aware zones for the REFERENCE ZONES card (iOS legend) — HRV gets its // baseline-relative zones from the window's samples further below. val physiology = try { val userProfile = db.userProfileDao().get() - apiKeyStore.physiologyProfile(userProfile) + apiKeyStore.physiologyProfile(userProfile, corrections) } catch (_: Exception) { UserPhysiologyProfile.UNKNOWN } if (metric == "bp") { @@ -1336,6 +1376,9 @@ class VitalDetailViewModel( fun convert(v: Double): Double = when (kind) { MeasurementKind.BLOOD_SUGAR -> glucoseUnit.fromMgdl(v + glucoseOffset) MeasurementKind.TEMPERATURE -> UnitConverter.temperature(v, unitSystem) + // Accuracy corrections, read-time only (docs/accuracy-check-plan.md). + MeasurementKind.HEART_RATE -> corrections.heartRate(v) + MeasurementKind.SPO2 -> corrections.spo2(v) else -> v } @@ -1364,7 +1407,7 @@ class VitalDetailViewModel( // Resting HR from the window's raw samples (low-percentile estimate). val resting = if (kind == MeasurementKind.HEART_RATE) - HeartRateZones.restingHeartRate(samples.map { it.value }) + HeartRateZones.restingHeartRate(samples.map { corrections.heartRate(it.value) }) else null // HRV zones are baseline-relative; the detail window (Week/Month) carries enough @@ -1409,6 +1452,13 @@ class VitalDetailViewModel( engineZones = engineZones, isDerived = derived.isNotEmpty(), usualRange = usualRange, + adjustedNote = when (kind) { + MeasurementKind.HEART_RATE -> corrections.describe(setOf( + com.pulseloop.health.accuracy.ComparisonMetric.HR_REST, com.pulseloop.health.accuracy.ComparisonMetric.HR_ACTIVE, + )) + MeasurementKind.SPO2 -> corrections.describe(setOf(com.pulseloop.health.accuracy.ComparisonMetric.SPO2)) + else -> null + }, loading = false, ) } } diff --git a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt new file mode 100644 index 00000000..9bce9ed1 --- /dev/null +++ b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt @@ -0,0 +1,147 @@ +package com.pulseloop.health.accuracy + +import com.pulseloop.data.entity.AccuracyCorrectionEntity +import com.pulseloop.data.entity.ActivityDailyEntity +import com.pulseloop.data.entity.DeviceEntity +import com.pulseloop.data.entity.SleepSessionEntity +import com.pulseloop.service.DailyCalorieEstimator +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertSame +import org.junit.Assert.assertTrue +import org.junit.Test + +class AccuracyCorrectionsTest { + + private val ring = DeviceEntity(id = "row", bleAddressHint = "aa:bb", firmwareVersion = "fw1") + + private fun c(metric: ComparisonMetric, value: Double, key: String = "AA:BB", enabled: Boolean = true, firmware: String? = "fw1", createdAt: Long = 0) = + AccuracyCorrectionEntity( + deviceKey = key, metric = metric.name, + kind = if (metric.correction == CorrectionKind.SCALE) AccuracyCorrectionEntity.KIND_SCALE else AccuracyCorrectionEntity.KIND_OFFSET, + value = value, fittedValue = value, fromCheckId = "c", enabled = enabled, firmware = firmware, createdAt = createdAt, + ) + + @Test + fun onlyThePairedRingsEnabledCorrectionsApply() { + val all = listOf( + c(ComparisonMetric.STEPS, 1.2), + c(ComparisonMetric.SPO2, 2.0, enabled = false), + c(ComparisonMetric.HR_REST, -3.0, key = "CC:DD"), + ) + val corr = AccuracyCorrections.of(ring, all, 40) + assertEquals(setOf(ComparisonMetric.STEPS), corr.items.keys) + assertEquals("AA:BB", corr.deviceKey) + } + + @Test + fun theDemoDeviceAndNoRingGetNothing() { + val all = listOf(c(ComparisonMetric.STEPS, 1.2, key = RingIdentity.DEMO_DEVICE_ID.uppercase())) + assertSame(Corrections.NONE, AccuracyCorrections.of(DeviceEntity(id = RingIdentity.DEMO_DEVICE_ID), all, null)) + assertSame(Corrections.NONE, AccuracyCorrections.of(null, all, null)) + } + + @Test + fun noCorrectionsChangesNothing() { + val n = Corrections.NONE + assertEquals(7_412, n.steps(7_412)) + assertEquals(64.0, n.heartRate(64.0), 0.0) + assertEquals(97.0, n.spo2(97.0), 0.0) + assertEquals(420, n.asleepMinutes(420)) + val day = ActivityDailyEntity(date = 0, steps = 100, distanceMeters = 80.0) + assertSame(day, n.day(day)) + assertNull(n.describe()) + } + + @Test + fun stepsAndDistanceScale() { + val corr = Corrections("K", mapOf( + ComparisonMetric.STEPS to c(ComparisonMetric.STEPS, 1.18), + ComparisonMetric.DISTANCE to c(ComparisonMetric.DISTANCE, 1.1), + )) + val day = corr.day(ActivityDailyEntity(date = 0, steps = 7_412, distanceMeters = 5_000.0, calories = 300.0)) + assertEquals(8_746, day.steps) + assertEquals(5_500.0, day.distanceMeters, 1e-9) + assertEquals(300.0, day.calories, 0.0) // not a corrected field + } + + @Test + fun heartRateUsesTheRestOrActiveOffsetBySplittingAtFlexHr() { + // Age 40: Flex-HR = 0.6 × 180 = 108. + val corr = Corrections("K", mapOf( + ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0), + ComparisonMetric.HR_ACTIVE to c(ComparisonMetric.HR_ACTIVE, 8.0), + ), age = 40) + assertEquals(57.0, corr.heartRate(60.0), 1e-9) + assertEquals(128.0, corr.heartRate(120.0), 1e-9) + } + + @Test + fun withOnlyOneHeartRateOffsetItAppliesAcrossTheBoard() { + val corr = Corrections("K", mapOf(ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0)), age = 40) + assertEquals(117.0, corr.heartRate(120.0), 1e-9) + } + + @Test + fun theBaselineMovesByTheRestingOffset_preferringAFittedRestingHr() { + val rest = Corrections("K", mapOf(ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0))) + assertEquals(55.0, rest.baseline(58.0), 1e-9) + val both = Corrections("K", mapOf( + ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0), + ComparisonMetric.RESTING_HR to c(ComparisonMetric.RESTING_HR, 2.0), + )) + assertEquals(60.0, both.baseline(58.0), 1e-9) + } + + @Test + fun spo2IsClampedAndSleepCorrectsOnlyTheTotal() { + val corr = Corrections("K", mapOf( + ComparisonMetric.SPO2 to c(ComparisonMetric.SPO2, 3.0), + ComparisonMetric.SLEEP_ASLEEP to c(ComparisonMetric.SLEEP_ASLEEP, -25.0), + )) + assertEquals(100.0, corr.spo2(99.0), 0.0) + val night = SleepSessionEntity(date = 0, startAt = 0, endAt = 1, totalMinutes = 420) + assertEquals(395, corr.sleep(night).totalMinutes) + assertEquals(0, corr.asleepMinutes(10)) + } + + @Test + fun theCaptionNamesWhatChanged() { + val corr = Corrections("K", mapOf( + ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0), + ComparisonMetric.STEPS to c(ComparisonMetric.STEPS, 1.18), + )) + assertEquals("steps ×1.18 · heart rate at rest −3.0 bpm", corr.describe()) + assertEquals("steps ×1.18", corr.describe(setOf(ComparisonMetric.STEPS))) + assertNull(corr.describe(setOf(ComparisonMetric.SPO2))) + } + + @Test + fun aCorrectionGoesStaleWithAgeOrAFirmwareChange() { + val now = 200L * 86_400_000L + assertFalse(AccuracyCorrections.isStale(c(ComparisonMetric.STEPS, 1.2, createdAt = now - 10 * 86_400_000L), ring, now)) + assertTrue(AccuracyCorrections.isStale(c(ComparisonMetric.STEPS, 1.2, createdAt = now - 100 * 86_400_000L), ring, now)) + assertTrue(AccuracyCorrections.isStale(c(ComparisonMetric.STEPS, 1.2, firmware = "fw0", createdAt = now), ring, now)) + } + + @Test + fun theAppShowsTheAdjustedCaloriesButFallsBackToTheRawOnes() { + val raw = ActivityDailyEntity(date = 0, source = DailyCalorieEstimator.RING_HISTORY_SOURCE, estimatedActiveCalories = 300.0) + assertEquals(300.0, DailyCalorieEstimator.displayActiveCalories(raw)!!, 0.0) + val adjusted = raw.copy(estimatedActiveCaloriesAdjusted = 340.0) + assertEquals(340.0, DailyCalorieEstimator.displayActiveCalories(adjusted)!!, 0.0) + // The export-facing figure ignores the adjusted copy entirely. + assertEquals(300.0, DailyCalorieEstimator.effectiveActiveCalories(adjusted)!!, 0.0) + // A device-reported figure wins over both, as before. + val device = adjusted.copy(source = "colmi", calories = 500.0) + assertEquals(500.0, DailyCalorieEstimator.displayActiveCalories(device)!!, 0.0) + } + + @Test + fun formattedValuesMatchTheirKind() { + assertEquals("×1.25", AccuracyCorrections.formatValue(ComparisonMetric.STEPS, 1.25)) + assertEquals("+25 min", AccuracyCorrections.formatValue(ComparisonMetric.SLEEP_ASLEEP, 25.0)) + assertEquals("−2.0 points", AccuracyCorrections.formatValue(ComparisonMetric.SPO2, -2.0)) + } +} From 070ac359ae2a11f26d9d7da1f0da41c2a7bcb341 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 16:13:16 +0000 Subject: [PATCH 8/9] Accuracy check Phase 5: shareable summary, and docs as built 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. --- AGENTS.md | 40 +++++++++ .../health/accuracy/AccuracyReportText.kt | 28 +++++++ .../pulseloop/ui/screens/AccuracyReportUi.kt | 14 ++++ .../health/accuracy/AccuracyComparisonTest.kt | 10 +++ docs/accuracy-check-plan.md | 82 ++++++++++++++++++- 5 files changed, 170 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index edb719bd..8bb41be3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -970,3 +970,43 @@ coordinator on the event bus, so every frame was persisted and handled twice. auto-reconnect) runs for the process's first composition only (`claimStartup()`). Re-running the stale-state reset would write DISCONNECTED over a live link. - A recreated Activity's first `ON_START` is not the startup's, so it does run `reconnectIfNeeded()`. + +## Accuracy check: what it may and may not change + +**Read this before touching `health/accuracy/`, the export's held-back records, or anything that +reads `AccuracyCorrections`.** Full design and the "As built" notes: `docs/accuracy-check-plan.md`. + +The feature compares the ring with another device's Health Connect records for a few days, holds +back the duplicate exports meanwhile, and can correct a consistent bias. Each rule below is there +because breaking it fails silently: + +- **Every reference read filters on `DataOrigin`.** Without it PulseLoop's own earlier exports, or + a third app re-syncing them, get compared with the ring and the report reads "perfect + agreement". A bridge app (Health Sync) can still echo PulseLoop's export back under its own + package, which no origin filter catches. That is what the HR echo check is for (an exact + second-and-beat match on most samples); keep it running on every scoring pass. +- **The reference's readings are never stored.** `accuracy_check_days` holds aggregates only. It + would be the first foreign health data in the archive, and the diagnostics export rule + (no readings in text people paste) applies to the "Copy summary" and "Share" texts too. +- **Held-back exports are filtered by data time, and the watermark still advances past them.** + Don't "fix" this into holding the watermark. That is what makes Skip-these-days the default + with nothing to undo, and what keeps a window record that is updated later (a re-synced night) + out of Health Connect. Export-them-too rewinds watermarks under + `HealthConnectExportWorker.passMutex`; a rewind outside the mutex can be overtaken by a pass in + flight. The pause set follows the **reference device**, never the ring's capability list, so + a ring swap can't open a duplication gap. +- **Corrections are read-time only, and never reach Health Connect.** Stored rows stay as the + ring sent them; it re-sends its history, so a rewritten row wouldn't stay rewritten anyway. + A derived figure that is also *exported* keeps a raw copy for the export: + `estimatedActiveCalories` (raw, exported) vs `estimatedActiveCaloriesAdjusted` (shown), and + `hrRestingBaseline` (raw, exported) vs `Corrections.baseline()` at read time. The display + helpers (`DailyCalorieEstimator.displayActiveCalories` / `displayCalories`) must not be used + by an exporter. A screen showing corrected figures carries the `AdjustedCaption`. +- **Corrections belong to one ring (BLE address) and only exist after a consistent-bias + verdict.** Don't widen them to "Inconsistent": a slider that moves the average of an erratic + ring is exactly the false fix the verdict exists to refuse. Sleep stages, onset/wake, HRV and + calories are report-only on purpose: vendors compute them differently, so a difference there + doesn't show which device is wrong. +- **A running check ends the moment a different ring is paired** (`AccuracyRingWatcher`, started + from `PulseLoopApplication`). Ring rows carry no device id, so a later sweep could not split + the two rings' data. diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt index 2afaaddb..36994eae 100644 --- a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyReportText.kt @@ -129,4 +129,32 @@ object AccuracyReportText { .filter { it.verdict == Verdict.CONSISTENTLY_HIGH || it.verdict == Verdict.CONSISTENTLY_LOW || it.verdict == Verdict.INCONSISTENT } .filter { it.metric.kind != ComparisonMetric.Kind.STAGES } .sortedByDescending { maxOf(abs(it.bias), it.mae) / it.band.coerceAtLeast(1e-6) } + + /** + * The shareable summary (plan, Phase 5): verdicts and headline differences with the ring's + * model and firmware — the kind of line that helps in an issue ("my SR08 counts ~20 % fewer + * steps"). Aggregates only, no day-by-day values and no readings from either device, for the + * same reason the diagnostics export carries none: this is text people paste in public. + */ + fun share( + ringLabel: String, + model: String?, + firmware: String?, + referenceLabel: String, + span: String, + summaries: List, + ): String = buildString { + appendLine("PulseLoop accuracy check: $ringLabel vs $referenceLabel ($span)") + val ring = listOfNotNull(model?.takeIf { it.isNotBlank() }, firmware?.takeIf { it.isNotBlank() }?.let { "firmware $it" }) + if (ring.isNotEmpty()) appendLine("Ring: " + ring.joinToString(", ")) + for (s in summaries) { + val headline = when { + s.verdict == Verdict.NOT_ENOUGH_DATA -> "not enough data" + s.metric.kind == ComparisonMetric.Kind.STAGES -> s.stageAgreement?.let { "same stage ${(it * 100).roundToInt()} % of the night" } ?: "no overlap" + else -> "${signed(s.metric, s.bias)} on average, ${verdictLabel(s.verdict).lowercase()} (${s.validDays} ${if (s.metric.source == ReferenceMetric.SLEEP || s.metric == ComparisonMetric.RESTING_HR || s.metric == ComparisonMetric.HRV) "nights" else "days"})" + } + appendLine("• ${s.metric.label}: $headline") + } + append("Agreement with the reference device, not a lab measurement.") + } } diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt index 274663c1..96f2ab59 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyReportUi.kt @@ -104,6 +104,20 @@ internal fun AccuracyReportSection( ) if (scoring) CircularProgressIndicator(Modifier.size(18.dp), strokeWidth = 2.dp) else TextButton(onClick = { rescore(force = true) }) { Text("Recompute") } + if (summaries.isNotEmpty()) TextButton(onClick = { + scope.launch { + val ring = db.deviceDao().currentReal()?.takeIf { RingIdentity.keyOf(it) == check.deviceKey } + val text = AccuracyReportText.share( + ringLabel = check.deviceLabel, model = ring?.wearableModelID, firmware = check.firmware, + referenceLabel = check.referenceLabel, span = AccuracyUiText.span(check), summaries = summaries, + ) + val send = android.content.Intent(android.content.Intent.ACTION_SEND).apply { + type = "text/plain" + putExtra(android.content.Intent.EXTRA_TEXT, text) + } + context.startActivity(android.content.Intent.createChooser(send, "Share accuracy report")) + } + }) { Text("Share") } } Text( "How your ring compares with ${check.referenceLabel}, the device you chose to trust. This is agreement between two " + diff --git a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt index f9e0174c..7469f6d6 100644 --- a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt +++ b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyComparisonTest.kt @@ -267,4 +267,14 @@ class AccuracyComparisonTest { assertEquals("23:30", AccuracyReportText.clock(-30.0)) assertEquals("07:05", AccuracyReportText.clock(425.0)) } + + @Test + fun theShareableSummaryHoldsVerdictsButNoDayValues() { + val steps = AccuracyComparison.summarize(ComparisonMetric.STEPS, (0 until 4).map { daily(ComparisonMetric.STEPS, it.toLong(), 7_123.0, 8_765.0) }) + val text = AccuracyReportText.share("SR08", "jring-sr08", "V138", "Health Sync (Huawei)", "21 Oct – 28 Oct", listOf(steps)) + assertTrue(text, text.contains("SR08 vs Health Sync (Huawei)")) + assertTrue(text, text.contains("firmware V138")) + assertTrue(text, text.contains("Steps: −19 % on average, consistently low (4 days)")) + assertFalse(text, text.contains("7123") || text.contains("7,123") || text.contains("8765") || text.contains("8,765")) + } } diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md index 3b612e16..b01d2d7b 100644 --- a/docs/accuracy-check-plan.md +++ b/docs/accuracy-check-plan.md @@ -1,6 +1,80 @@ # Accuracy check — compare the ring against another device via Health Connect -Status: **Phase 0 implemented** (2026-10-21), waiting on a real-device scan. Later phases are plan only. +Status: **all phases implemented** (2026-10-21), not yet run on real hardware. The plan below is +kept as written; **"As built"** right after it records where the code differs and why. The first +real check (Huawei through Health Sync) still has to confirm the Health Sync questions under +Open questions. + +## As built (2026-10-21) + +Code: `health/accuracy/` (engine, scorer, controller, corrections, export pause), screens in +`ui/screens/AccuracyCheckUi.kt` and `AccuracyReportUi.kt`, Room v36. Commits per phase on +`claude/brave-cerf-2jew36`. + +**Export pause: held back by data time, not by holding the watermark.** The plan said to hold each +paused unit's watermark. The code does the opposite. A record of a paused type whose data time +overlaps the check window is dropped from the pass, and its watermark advances past it like a +never-exportable row (`ExportPause`). That makes "Skip these days" the default with nothing to do +on resume except close the window. It also keeps the window skipped: a window record updated +later (a re-synced night) re-selects, meets the same closed exclusion, and is dropped again. +"Export them too" removes the exclusion and rewinds the affected watermarks to where holding back +began (`HealthConnectPrefsStore.rewindWatermarks`: never forward, never past a new-only user's +consent), under the export's pass mutex. Side effect: because the rule is overlap, the whole-day +activity record for the day a check starts and the day it ends is held back too, since its total +includes steps from inside the window. +- The export units are finer than the settings rows: steps, distance and active calories are + separate (`ExportUnit`). Workout calorie and distance siblings are held back with the daily + records; the workout session itself always exports. +- Exclusions live in Room with the checks and ride the archive, so a restore can't forget them. + +**Lifecycle.** `AccuracyCheckController` owns every state change: RUNNING → AWAITING_RESUME → +DONE. A one-shot worker at the planned end, a 6-hourly backstop and a notification end the check +on time. A different ring ends it immediately: `AccuracyRingWatcher` watches the device row from +`PulseLoopApplication`, because ring data has no device id and can't be split afterwards. A row +that only *learns* its address re-keys the check instead of ending it. The pause set grows from +the screen (foreground) and from the worker when Health Connect allows background reads +(`READ_HEALTH_DATA_IN_BACKGROUND`, optional). + +**Scoring** (`AccuracyScorer`, foreground, re-read at most every 30 min unless "Recompute"): +- Daily totals count only whole local days inside the window. A day is dropped when the reference + has fewer than 500 steps or the ring has none (not worn on both). +- A day is scored once the reference has delivered past its end, or 24 h after it ends. Until + then it shows "waiting for ". +- Sleep: the ring's longest session per waking day vs the reference's, by time asleep, onset and + wake (as minutes from the waking day's midnight), and minute-by-minute stage agreement. + Unstaged minutes count neither way. +- Heart rate: each ring sample is paired with the nearest unused reference sample. The window is + half the reference's own cadence, clamped to 60–150 s, so a sparse bridge still pairs. Samples + split into rest (asleep, or a 15-min bucket under 50 steps) and active (a workout, or 300+ + steps); anything in between is skipped. +- SpO₂ pairs within 5 min. Resting HR and HRV are compared per night, using `NightlyVitals` for + the ring. +- The HR echo check runs on every scoring pass, and the report warns when it trips. +- Verdict (`AccuracyComparison.summarize`): Agrees / Consistently high or low / Inconsistent / + Not enough data. A consistent bias needs ≥ 80 % of days pointing the same way and a + day-to-day wobble smaller than the bias. + +**Report differences from the plan.** No Bland-Altman scatter or bar charts. Each metric shows +its limits of agreement as text and a per-day list. There is no "hours where the ring missed +activity" figure either. Bands are editable per metric (slider) and stored on the check. + +**Corrections differences from the plan.** +- Sleep onset/wake are report-only (no offset): shifting a hypnogram's clock would be a second, + stranger kind of correction. Time asleep does get an offset, applied to the night's total + only; stage blocks are never touched. +- A single heart-rate sample's context isn't known at read time, so rest vs active is split at + Flex-HR (0.6 × (220 − age)), the calorie estimator's own threshold. +- Applied in the ViewModels (Today, Vitals and its detail, Sleep, Activity). The home-screen + widgets share `VitalsViewModel.buildState`, so they show corrected heart rate and SpO₂ too, + but are too small for the caption. Known gap. +- Not applied to: the coach's tools and scores context, the live workout stream, the + Health Connect export, and stored rows. All of these read raw. +- Applied to everything shown while that ring is paired, history included, because stored data + carries no ring id. +- A steps correction supersedes the existing phone step calibration (`StepCalibration`) on + Today, rather than stacking on it. +- The adjusted calorie copy is recomputed over 90 days when a correction changes, without + bumping `updatedAt`, so the export doesn't re-read those days. ## The idea @@ -323,9 +397,9 @@ say it is derived"* (#67), and the ring re-supplying its own history on every sy `lastModifiedTime − endTime`, devices from `Metadata.device`, sleep stage types, and the HR echo check), `ReferenceSourceScanner` (foreground read of the last 7 days), `ReferenceSurveyText` (wording + "Copy summary", counts and timings only). Screen: - Settings → Accuracy check (`AccuracyCheckUi.kt`). Nothing is stored yet. **Next:** run the - scan on the Huawei/Health Sync setup and paste the copied summary; it answers the four - Health Sync questions under Open questions. + Settings → Accuracy check (`AccuracyCheckUi.kt`). **Still to do on hardware:** run the scan on + the Huawei/Health Sync setup and paste the copied summary; it answers the four Health Sync + questions under Open questions. 1. **Session lifecycle + per-type export pause**: table, the exporter's per-row pause gate that holds watermarks, daily refresh of the pause set, export-screen state, end job, notification, resume dialog with the per-kind skip, early end on a ring change. Unit-test the skip and that From c31230663149cfa21a0173e31059ec8d4085f954 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 16:22:56 +0000 Subject: [PATCH 9/9] Accuracy check: correct and label the widgets, the coach and the live workout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AGENTS.md | 4 ++- .../coach/context/CoachContextBuilder.kt | 17 ++++++----- .../summaries/CoachSummaryContextBuilder.kt | 13 ++++---- .../pulseloop/coach/tools/CoachDataAccess.kt | 13 +++++--- .../coach/tools/ToolImplementations.kt | 25 +++++++++++----- .../health/accuracy/AccuracyCorrections.kt | 16 ++++++++++ .../NotificationContextBuilder.kt | 10 ++++--- .../pulseloop/service/LiveWorkoutManager.kt | 10 ++++++- .../java/com/pulseloop/ui/PulseLoopApp.kt | 1 + .../pulseloop/ui/screens/AccuracyCheckUi.kt | 12 ++++++++ .../pulseloop/ui/screens/ActivityScreen.kt | 3 +- .../com/pulseloop/ui/screens/RecordScreen.kt | 5 ++++ .../ui/screens/WorkoutSummaryScreen.kt | 15 +++++++--- .../com/pulseloop/widgets/WidgetSnapshot.kt | 6 ++++ .../widgets/WidgetSnapshotPublisher.kt | 24 +++++++++++---- .../pulseloop/widgets/WidgetTileRenderer.kt | 22 +++++++++++--- .../accuracy/AccuracyCorrectionsTest.kt | 30 +++++++++++++++++++ docs/accuracy-check-plan.md | 13 +++++--- 18 files changed, 191 insertions(+), 48 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8bb41be3..501b7c40 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1001,7 +1001,9 @@ because breaking it fails silently: `estimatedActiveCalories` (raw, exported) vs `estimatedActiveCaloriesAdjusted` (shown), and `hrRestingBaseline` (raw, exported) vs `Corrections.baseline()` at read time. The display helpers (`DailyCalorieEstimator.displayActiveCalories` / `displayCalories`) must not be used - by an exporter. A screen showing corrected figures carries the `AdjustedCaption`. + by an exporter. A screen showing corrected figures carries the `AdjustedCaption` (a widget tile, + its `adjusted` flag). The coach reads through the corrections too and is told so; a workout's + stored samples and summary stay raw because Health Connect and Strava get them. - **Corrections belong to one ring (BLE address) and only exist after a consistent-bias verdict.** Don't widen them to "Inconsistent": a slider that moves the average of an erratic ring is exactly the false fix the verdict exists to refuse. Sleep stages, onset/wake, HRV and diff --git a/app/src/main/java/com/pulseloop/coach/context/CoachContextBuilder.kt b/app/src/main/java/com/pulseloop/coach/context/CoachContextBuilder.kt index 09035be0..3c518612 100644 --- a/app/src/main/java/com/pulseloop/coach/context/CoachContextBuilder.kt +++ b/app/src/main/java/com/pulseloop/coach/context/CoachContextBuilder.kt @@ -26,11 +26,13 @@ object CoachContextBuilder { val goal = db.userGoalDao().get() val todayStart = localStartOfDay(now) - val todayActivity = db.activityDailyDao().byDay(todayStart) + // The coach is given what the app shows: accuracy corrections applied, and said so below. + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val todayActivity = db.activityDailyDao().byDay(todayStart)?.let(corrections::day) // Latest HR / SpO2 - val latestHr = db.measurementDao().latest(MeasurementKind.HEART_RATE.name, now) - val latestSpo2 = db.measurementDao().latest(MeasurementKind.SPO2.name, now) + val latestHr = db.measurementDao().latest(MeasurementKind.HEART_RATE.name, now)?.let(corrections::heartRate) + val latestSpo2 = db.measurementDao().latest(MeasurementKind.SPO2.name, now)?.let(corrections::spo2) // 7-day trends. Real wins over seeded rows once the ring has synced (`DemoDataPolicy`): // a connect no longer purges demo data, so without this the coach LLM is handed a @@ -38,7 +40,7 @@ object CoachContextBuilder { val activityHasReal = db.activityDailyDao().hasReal() val sevenDaysAgo = todayStart - 7 * 24 * 3600_000L val activityWeek = (if (activityHasReal) db.activityDailyDao().recentReal(7) - else db.activityDailyDao().recent(7)).filter { it.date >= sevenDaysAgo } + else db.activityDailyDao().recent(7)).filter { it.date >= sevenDaysAgo }.map(corrections::day) val stepsWeek = activityWeek.map { it.steps.toDouble() } val daysAvailable = activityWeek.count { it.steps > 0 } @@ -46,15 +48,16 @@ object CoachContextBuilder { val hr24h = if (db.measurementDao().hasReal(MeasurementKind.HEART_RATE.name)) db.measurementDao().rangeReal(MeasurementKind.HEART_RATE.name, now - 24 * 3600_000L, now) else db.measurementDao().range(MeasurementKind.HEART_RATE.name, now - 24 * 3600_000L, now) + val hr24hShown = hr24h.map(corrections::measurement) val restingHr = if (hr24h.isNotEmpty()) { - val sorted = hr24h.map { it.value }.sorted() + val sorted = hr24hShown.map { it.value }.sorted() sorted[(sorted.size * 0.25).toInt().coerceAtMost(sorted.size - 1)] } else null // Sleep val sleepHasReal = db.sleepSessionDao().hasReal() val latestSleep = (if (sleepHasReal) db.sleepSessionDao().recentReal(1) - else db.sleepSessionDao().recent(1)).firstOrNull() + else db.sleepSessionDao().recent(1)).firstOrNull()?.let(corrections::sleep) val completeness = profileCompleteness(profile) val warnings = DataQualityAnalyzer.warnings( @@ -71,7 +74,7 @@ object CoachContextBuilder { (activityWeek.isNotEmpty() || latestSleep != null || hr24h.isNotEmpty()), ), now = now, - ) + ) + listOfNotNull(corrections.coachNote()) return CoachContextPacket( today = LocalDate.now().toString(), diff --git a/app/src/main/java/com/pulseloop/coach/summaries/CoachSummaryContextBuilder.kt b/app/src/main/java/com/pulseloop/coach/summaries/CoachSummaryContextBuilder.kt index 41fd1192..ad5298c6 100644 --- a/app/src/main/java/com/pulseloop/coach/summaries/CoachSummaryContextBuilder.kt +++ b/app/src/main/java/com/pulseloop/coach/summaries/CoachSummaryContextBuilder.kt @@ -46,12 +46,14 @@ object CoachSummaryContextBuilder { /** Readiness and activity scores (docs/oura-ux-analysis.md phase 5). */ val scores: com.pulseloop.service.ScoresContext? = null, ) + // What the app shows: accuracy corrections applied (packet.dataQualityWarnings says so). + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) val activity = db.activityDailyDao().byDay( java.time.LocalDate.now().atStartOfDay(java.time.ZoneId.systemDefault()) .toInstant().toEpochMilli() - ) - val latestHr = db.measurementDao().latest(com.pulseloop.ring.MeasurementKind.HEART_RATE.name) - val latestSpo2 = db.measurementDao().latest(com.pulseloop.ring.MeasurementKind.SPO2.name) + )?.let(corrections::day) + val latestHr = db.measurementDao().latest(com.pulseloop.ring.MeasurementKind.HEART_RATE.name)?.let(corrections::heartRate) + val latestSpo2 = db.measurementDao().latest(com.pulseloop.ring.MeasurementKind.SPO2.name)?.let(corrections::spo2) val tp = TodayPacket( today = todayDate, @@ -92,12 +94,13 @@ object CoachSummaryContextBuilder { suspend fun sleepDay(db: PulseLoopDatabase): Built? { val todayStart = java.time.LocalDate.now().atStartOfDay(java.time.ZoneId.systemDefault()) .toInstant().toEpochMilli() - val session = db.sleepSessionDao().byDay(todayStart) ?: return null + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val session = db.sleepSessionDao().byDay(todayStart)?.let(corrections::sleep) ?: return null if (session.totalMinutes <= 0) return null val blocks = db.sleepStageBlockDao().forSession(session.id) val score = SleepScore.calculate(session, blocks) - val activitySteps = db.activityDailyDao().byDay(todayStart)?.steps + val activitySteps = db.activityDailyDao().byDay(todayStart)?.let(corrections::day)?.steps @Serializable data class SleepDayPacket( diff --git a/app/src/main/java/com/pulseloop/coach/tools/CoachDataAccess.kt b/app/src/main/java/com/pulseloop/coach/tools/CoachDataAccess.kt index b3be595f..133ea722 100644 --- a/app/src/main/java/com/pulseloop/coach/tools/CoachDataAccess.kt +++ b/app/src/main/java/com/pulseloop/coach/tools/CoachDataAccess.kt @@ -1,5 +1,6 @@ package com.pulseloop.coach.tools +import com.pulseloop.health.accuracy.AccuracyCorrections import com.pulseloop.data.PulseLoopDatabase import com.pulseloop.data.entity.* import com.pulseloop.ring.MeasurementKind @@ -79,7 +80,9 @@ object CoachDataAccess { db: PulseLoopDatabase, kind: MeasurementKind, start: String, end: String ): List { val bounds = dayBounds(start, end) ?: return emptyList() - return db.measurementDao().range(kind.name, bounds.first, bounds.second) + // The coach sees what the app shows: accuracy corrections applied (read-time only). + val c = AccuracyCorrections.load(db) + return db.measurementDao().range(kind.name, bounds.first, bounds.second).map(c::measurement) } suspend fun activityRows( @@ -88,12 +91,13 @@ object CoachDataAccess { val s = parseLocalDate(start) ?: return emptyList() val e = parseLocalDate(end) ?: return emptyList() val recent = db.activityDailyDao().recent(90) // broad window; filter in Kotlin - return recent.filter { it.date >= s && it.date <= e }.sortedBy { it.date } + val c = AccuracyCorrections.load(db) + return recent.filter { it.date >= s && it.date <= e }.sortedBy { it.date }.map(c::day) } suspend fun activityRow(db: PulseLoopDatabase, date: String): ActivityDailyEntity? { val day = parseLocalDate(date) ?: return null - return db.activityDailyDao().byDay(day) + return db.activityDailyDao().byDay(day)?.let(AccuracyCorrections.load(db)::day) } suspend fun sleepSessions( @@ -102,7 +106,8 @@ object CoachDataAccess { val s = parseLocalDate(start) ?: return emptyList() val e = parseLocalDate(end) ?: return emptyList() val recent = db.sleepSessionDao().recent(90) - return recent.filter { it.date in s..e }.sortedBy { it.date } + val c = AccuracyCorrections.load(db) + return recent.filter { it.date in s..e }.sortedBy { it.date }.map(c::sleep) } suspend fun activitySessions( diff --git a/app/src/main/java/com/pulseloop/coach/tools/ToolImplementations.kt b/app/src/main/java/com/pulseloop/coach/tools/ToolImplementations.kt index cb282b27..c5bd66c2 100644 --- a/app/src/main/java/com/pulseloop/coach/tools/ToolImplementations.kt +++ b/app/src/main/java/com/pulseloop/coach/tools/ToolImplementations.kt @@ -59,13 +59,15 @@ object RetrievalTools { val result = kotlinx.coroutines.runBlocking { val dayTs = CoachDataAccess.parseLocalDate(date) if (dayTs == null) return@runBlocking """{"error":"invalid date: $date"}""" - val activity = db.activityDailyDao().byDay(dayTs) - val hrVals = db.measurementDao().range(MeasurementKind.HEART_RATE.name, dayTs, dayTs + 86400000L) + // What the app shows: accuracy corrections applied (read-time only). + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val activity = db.activityDailyDao().byDay(dayTs)?.let(corrections::day) + val hrVals = db.measurementDao().range(MeasurementKind.HEART_RATE.name, dayTs, dayTs + 86400000L).map(corrections::measurement) val hrStats = if (hrVals.isNotEmpty()) { val vals = hrVals.map { it.value } """"mean":${(vals.average() * 10).toLong() / 10.0},"min":${vals.minOrNull()!!.toInt()},"max":${vals.maxOrNull()!!.toInt()}"""" } else null - val sleep = db.sleepSessionDao().byDay(dayTs) + val sleep = db.sleepSessionDao().byDay(dayTs)?.let(corrections::sleep) """{"date":"$date","data_available":${activity != null || hrVals.isNotEmpty()},"activity":{"${if (activity != null) """steps":${activity.steps},"calories":${(activity.calories * 10).toLong() / 10.0},"distance_km":${(activity.distanceMeters / 1000 * 10).toLong() / 10.0},"active_minutes":${activity.activeMinutes}""" else """steps":0,"calories":0,"distance_km":0,"active_minutes":0"""}},"hr":{${hrStats ?: """"mean":null,"min":null,"max":null""""}},"sleep":${if (sleep != null) """{"total_min":${sleep.totalMinutes},"score":${sleep.totalMinutes / 5}}""" else "null"}}""" } ToolResult(result) @@ -174,7 +176,8 @@ object RetrievalTools { val sb = StringBuilder("{") sb.append(""""start_date":"$start","end_date":"$end",""") if ("activity" in include || "goals" in include) { - val rows = db.activityDailyDao().recent(365).filter { + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val rows = db.activityDailyDao().recent(365).map(corrections::day).filter { val d = java.time.Instant.ofEpochMilli(it.date).atZone(java.time.ZoneId.systemDefault()).toLocalDate().toString() d >= start && d <= end } @@ -304,7 +307,10 @@ object RetrievalTools { val params = Json.parseToJsonElement(jsonParams).jsonObject val range = params["range"]?.jsonPrimitive?.content ?: "week" val limit = when (range) { "week" -> 7; "month" -> 30; else -> 365 } - val sessions = kotlinx.coroutines.runBlocking { db.sleepSessionDao().recent(limit) } + val sessions = kotlinx.coroutines.runBlocking { + val c = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + db.sleepSessionDao().recent(limit).map(c::sleep) + } val avgMin = if (sessions.isNotEmpty()) sessions.map { it.totalMinutes }.average().toInt() else 0 ToolResult("""{"range":"$range","nights_tracked":${sessions.size},"expected_nights":$limit,"avg_total_min":$avgMin,"note":"experimental decoder (light/deep/awake only)"}""") } @@ -325,7 +331,9 @@ object RetrievalTools { val db = ctx.db ?: return@CoachToolDef ToolResult("""{"error":"database not available"}""", isError = true) val goal = kotlinx.coroutines.runBlocking { db.userGoalDao().get() } val todayStart = java.time.Instant.now().atZone(java.time.ZoneId.systemDefault()).truncatedTo(java.time.temporal.ChronoUnit.DAYS).toInstant().toEpochMilli() - val today = kotlinx.coroutines.runBlocking { db.activityDailyDao().byDay(todayStart) } + val today = kotlinx.coroutines.runBlocking { + db.activityDailyDao().byDay(todayStart)?.let(com.pulseloop.health.accuracy.AccuracyCorrections.load(db)::day) + } ToolResult("""{"today":{"steps":${today?.steps ?: 0},"steps_goal":${goal?.steps ?: 10000},"active_minutes":${today?.activeMinutes ?: 0},"active_minutes_goal":${goal?.activeMinutes ?: 45}},"sleep_hours_goal":${(goal?.sleepMinutes ?: 480) / 60}}""") } @@ -343,7 +351,10 @@ object RetrievalTools { )), ) { _, ctx -> val db = ctx.db ?: return@CoachToolDef ToolResult("""{"error":"database not available"}""", isError = true) - val recentSteps = kotlinx.coroutines.runBlocking { db.activityDailyDao().recent(14) }.map { it.steps.toDouble() } + val recentSteps = kotlinx.coroutines.runBlocking { + val c = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + db.activityDailyDao().recent(14).map { c.steps(it.steps).toDouble() } + } val stepOutliers = AnalysisEngine.outliers(recentSteps) ToolResult("""{"steps_outliers":${stepOutliers.size},"steps_analyzed":${recentSteps.size}}""") } diff --git a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt index 60226e48..3e8a1370 100644 --- a/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt +++ b/app/src/main/java/com/pulseloop/health/accuracy/AccuracyCorrections.kt @@ -79,6 +79,22 @@ data class Corrections( fun sleep(s: com.pulseloop.data.entity.SleepSessionEntity): com.pulseloop.data.entity.SleepSessionEntity = if (!has(ComparisonMetric.SLEEP_ASLEEP)) s else s.copy(totalMinutes = asleepMinutes(s.totalMinutes)) + /** A stored reading as shown: heart rate and SpO₂ corrected, any other kind unchanged. */ + fun measurement(m: com.pulseloop.data.entity.MeasurementEntity): com.pulseloop.data.entity.MeasurementEntity = when (m.kindRaw) { + com.pulseloop.ring.MeasurementKind.HEART_RATE.name -> if (has(ComparisonMetric.HR_REST) || has(ComparisonMetric.HR_ACTIVE)) m.copy(value = heartRate(m.value)) else m + com.pulseloop.ring.MeasurementKind.SPO2.name -> if (has(ComparisonMetric.SPO2)) m.copy(value = spo2(m.value)) else m + else -> m + } + + /** + * The line the coach is told when it's handed corrected figures, so it neither presents them + * as raw ring readings nor "corrects" them a second time. + */ + fun coachNote(): String? = describe()?.let { + "Some figures are adjusted by the user's accuracy check against another device ($it). " + + "They are what the app shows; the ring's stored readings are unchanged." + } + /** "Steps ×1.18 · heart rate at rest −3.0 bpm" — the caption a corrected screen carries. */ fun describe(only: Set? = null): String? = items.values .mapNotNull { c -> ComparisonMetric.byName(c.metric)?.let { it to c } } diff --git a/app/src/main/java/com/pulseloop/notifications/NotificationContextBuilder.kt b/app/src/main/java/com/pulseloop/notifications/NotificationContextBuilder.kt index 89d6a78c..574111d7 100644 --- a/app/src/main/java/com/pulseloop/notifications/NotificationContextBuilder.kt +++ b/app/src/main/java/com/pulseloop/notifications/NotificationContextBuilder.kt @@ -32,14 +32,16 @@ object NotificationContextBuilder { // Today's activity val todayStart = localStartOfDay(now) - val todayActivity = db.activityDailyDao().byDay(todayStart) + // What the app shows: accuracy corrections applied (read-time only). + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val todayActivity = db.activityDailyDao().byDay(todayStart)?.let(corrections::day) // Latest sleep - val latestSleep = db.sleepSessionDao().recent(1).firstOrNull() + val latestSleep = db.sleepSessionDao().recent(1).firstOrNull()?.let(corrections::sleep) // 12h HR & SpO2 stats - val hrRows = db.measurementDao().range(MeasurementKind.HEART_RATE.name, cutoff, now) - val spo2Rows = db.measurementDao().range(MeasurementKind.SPO2.name, cutoff, now) + val hrRows = db.measurementDao().range(MeasurementKind.HEART_RATE.name, cutoff, now).map(corrections::measurement) + val spo2Rows = db.measurementDao().range(MeasurementKind.SPO2.name, cutoff, now).map(corrections::measurement) val hrStats = if (hrRows.isNotEmpty()) { Stats( diff --git a/app/src/main/java/com/pulseloop/service/LiveWorkoutManager.kt b/app/src/main/java/com/pulseloop/service/LiveWorkoutManager.kt index db2b5976..7a8db7b0 100644 --- a/app/src/main/java/com/pulseloop/service/LiveWorkoutManager.kt +++ b/app/src/main/java/com/pulseloop/service/LiveWorkoutManager.kt @@ -30,6 +30,8 @@ class LiveWorkoutManager( val latestHeartRate: Int? = null, val latestSpO2: Int? = null, val hrZone: HeartRateZones.Zone = HeartRateZones.Zone.REST, + /** [latestHeartRate] carries an accuracy-check correction; the screen says so. */ + val heartRateAdjusted: Boolean = false, /** Set when a finish completes — the record route observes this to navigate to the * summary, since a finish from the notification action has no button handler to do it * (iOS routes off state the same way after an App Group command). */ @@ -220,6 +222,11 @@ class LiveWorkoutManager( private fun startTick(session: ActivitySessionEntity) { tickJob?.cancel() tickJob = scope.launch { + // Accuracy corrections for the live readout and its zone (read-time only: the samples + // the workout stores, and its summary, stay as measured — they reach Health Connect). + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + val adjusted = corrections.has(com.pulseloop.health.accuracy.ComparisonMetric.HR_ACTIVE) || + corrections.has(com.pulseloop.health.accuracy.ComparisonMetric.HR_REST) while (isActive) { val now = System.currentTimeMillis() // The live clock shows *active* time — wall time minus completed pauses (iOS @@ -228,7 +235,7 @@ class LiveWorkoutManager( // always current. val elapsed = maxOf(0, ((now - session.startedAt) / 1000.0 - session.totalPauseSeconds).toInt()) val distance = gps.state.value.totalDistance - val hr = coordinator.latestHRValue + val hr = coordinator.latestHRValue?.let { kotlin.math.round(corrections.heartRate(it.toDouble())).toInt() } val zone = hr?.let { HeartRateZones.zoneFor(it) } ?: HeartRateZones.Zone.REST _state.value = _state.value.copy( @@ -236,6 +243,7 @@ class LiveWorkoutManager( distanceMeters = distance, latestHeartRate = hr, hrZone = zone, + heartRateAdjusted = adjusted && hr != null, ) if (elapsed % 5 == 0) refreshNotification() diff --git a/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt b/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt index 9a58bc6f..a914269a 100644 --- a/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt +++ b/app/src/main/java/com/pulseloop/ui/PulseLoopApp.kt @@ -753,6 +753,7 @@ fun PulseLoopApp() { elapsedSeconds = workoutState.elapsedSeconds, distanceMeters = workoutState.distanceMeters, heartRate = workoutState.latestHeartRate, + heartRateAdjusted = workoutState.heartRateAdjusted, spO2 = workoutState.latestSpO2, isPaused = workoutState.isPaused, useGps = workoutState.activeSession?.useGps ?: true, diff --git a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt index c73afb0e..02c063bc 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/AccuracyCheckUi.kt @@ -427,6 +427,18 @@ internal fun AdjustedCaption(note: String) { ) } +/** The paired ring's accuracy corrections, for a composable that formats stored figures itself. */ +@Composable +internal fun rememberAccuracyCorrections(): com.pulseloop.health.accuracy.Corrections { + val context = LocalContext.current + val db = remember { PulseLoopDatabase.getInstance(context) } + val tick by com.pulseloop.health.accuracy.AccuracyCorrections.flow(db).collectAsState(initial = com.pulseloop.health.accuracy.Corrections.NONE) + val loaded by androidx.compose.runtime.produceState(com.pulseloop.health.accuracy.Corrections.NONE, tick) { + value = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) + } + return loaded +} + /** Today's one-line banner while a check is open. */ @Composable internal fun AccuracyCheckBanner(c: AccuracyCheckEntity, onOpen: () -> Unit) { diff --git a/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt index 524d093f..35019a8f 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/ActivityScreen.kt @@ -460,6 +460,7 @@ private fun SummaryMetric(label: String, value: String, unit: String?, color: Co /** One workout in the TODAY list / history sheet (ActivityWorkoutRow in Swift). */ @Composable fun ActivityWorkoutRow(session: ActivitySessionEntity, units: UnitSystem, onTap: () -> Unit) { + val corrections = rememberAccuracyCorrections() val shape = RoundedCornerShape(8.dp) val durationSec = session.endedAt?.let { ((it - session.startedAt) / 1000 - session.totalPauseSeconds).toInt() } Row( @@ -502,7 +503,7 @@ fun ActivityWorkoutRow(session: ActivitySessionEntity, units: UnitSystem, onTap: ) } session.avgHeartRate?.let { - Text("${it.toInt()} bpm avg", fontSize = 12.sp, color = PulseColors.textSecondary) + Text("${corrections.heartRate(it).toInt()} bpm avg", fontSize = 12.sp, color = PulseColors.textSecondary) } Spacer(Modifier.weight(1f)) if (session.useGps && session.gpsPointCount > 1) { diff --git a/app/src/main/java/com/pulseloop/ui/screens/RecordScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/RecordScreen.kt index 6fd35540..8c00a414 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/RecordScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/RecordScreen.kt @@ -30,6 +30,8 @@ fun RecordScreen( elapsedSeconds: Int = 0, distanceMeters: Double = 0.0, heartRate: Int? = null, + /** The heart rate carries an accuracy-check correction (labelled wherever shown). */ + heartRateAdjusted: Boolean = false, spO2: Int? = null, isPaused: Boolean = false, useGps: Boolean = true, @@ -98,6 +100,9 @@ fun RecordScreen( HeartRateZones.Zone.MAX -> PulseColors.zoneRed } Text(hrText, style = MaterialTheme.typography.headlineLarge, color = zoneColor) + if (heartRateAdjusted) { + Text("adjusted by your accuracy check", style = MaterialTheme.typography.labelSmall, color = MaterialTheme.colorScheme.onSurfaceVariant) + } Text(hrZone.label, style = MaterialTheme.typography.labelMedium, color = zoneColor) } } diff --git a/app/src/main/java/com/pulseloop/ui/screens/WorkoutSummaryScreen.kt b/app/src/main/java/com/pulseloop/ui/screens/WorkoutSummaryScreen.kt index 2104ade4..01f61992 100644 --- a/app/src/main/java/com/pulseloop/ui/screens/WorkoutSummaryScreen.kt +++ b/app/src/main/java/com/pulseloop/ui/screens/WorkoutSummaryScreen.kt @@ -508,14 +508,21 @@ private fun SummaryHeroBand(s: ActivitySessionEntity, durationSec: Int?, units: /** Secondary stat tiles, 3-per-row (WorkoutMetricsSections.statsGrid). */ @Composable private fun StatsGrid(s: ActivitySessionEntity) { + // Accuracy corrections at display only: the stored summary is what Health Connect and Strava get. + val corrections = rememberAccuracyCorrections() + fun hr(v: Double?) = v?.let { "${corrections.heartRate(it).toInt()}" } ?: "—" val stats = buildList { if (s.useGps) add("Calories" to (s.calories?.let { "${it.toInt()}" } ?: "—")) - add("Avg HR" to (s.avgHeartRate?.let { "${it.toInt()}" } ?: "—")) - add("Max HR" to (s.maxHeartRate?.let { "${it.toInt()}" } ?: "—")) - add("Min HR" to (s.minHeartRate?.let { "${it.toInt()}" } ?: "—")) - add("SpO₂" to (s.latestSpO2?.let { "${it.toInt()}%" } ?: "—")) + add("Avg HR" to hr(s.avgHeartRate)) + add("Max HR" to hr(s.maxHeartRate)) + add("Min HR" to hr(s.minHeartRate)) + add("SpO₂" to (s.latestSpO2?.let { "${corrections.spo2(it).toInt()}%" } ?: "—")) } Column(verticalArrangement = Arrangement.spacedBy(12.dp)) { + corrections.describe(setOf( + com.pulseloop.health.accuracy.ComparisonMetric.HR_REST, com.pulseloop.health.accuracy.ComparisonMetric.HR_ACTIVE, + com.pulseloop.health.accuracy.ComparisonMetric.SPO2, + ))?.let { AdjustedCaption(it) } stats.chunked(3).forEach { row -> Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(12.dp)) { row.forEach { (label, value) -> diff --git a/app/src/main/java/com/pulseloop/widgets/WidgetSnapshot.kt b/app/src/main/java/com/pulseloop/widgets/WidgetSnapshot.kt index e8024d69..df358995 100644 --- a/app/src/main/java/com/pulseloop/widgets/WidgetSnapshot.kt +++ b/app/src/main/java/com/pulseloop/widgets/WidgetSnapshot.kt @@ -76,6 +76,8 @@ data class WidgetActivityPayload( val stepsText: String? = null, val distanceText: String? = null, val caloriesText: String? = null, + /** Steps or distance carry an accuracy-check correction; the tile says so. */ + val adjusted: Boolean = false, ) // ─────────────────────────── Sleep (duration + stage bar + score tile) ─────────────────────────── @@ -85,6 +87,8 @@ data class WidgetSleepPayload( val durationText: String, val score: Int, val segments: List = emptyList(), + /** The duration carries an accuracy-check correction; the tile says so. */ + val adjusted: Boolean = false, ) { @Serializable data class Segment( @@ -147,6 +151,8 @@ data class WidgetMetricPayload( val kind: String, val title: String, val valueText: String, + /** The readings carry an accuracy-check correction; the tile says so. Defaulted for old snapshots. */ + val adjusted: Boolean = false, /** The raw reading behind [valueText] in display units (gauge needle position) — never parse * the locale-formatted [valueText] back. Defaulted so pre-field snapshots still decode. */ val latestValue: Double? = null, diff --git a/app/src/main/java/com/pulseloop/widgets/WidgetSnapshotPublisher.kt b/app/src/main/java/com/pulseloop/widgets/WidgetSnapshotPublisher.kt index 1f6c9c70..6eca16b2 100644 --- a/app/src/main/java/com/pulseloop/widgets/WidgetSnapshotPublisher.kt +++ b/app/src/main/java/com/pulseloop/widgets/WidgetSnapshotPublisher.kt @@ -1,5 +1,7 @@ package com.pulseloop.widgets +import com.pulseloop.health.accuracy.ComparisonMetric +import com.pulseloop.health.accuracy.Corrections import android.appwidget.AppWidgetManager import android.content.ComponentName import android.content.Context @@ -157,11 +159,18 @@ object WidgetSnapshotPublisher { val units = keyStore?.resolvedUnitSystem ?: UnitSystem.METRIC val vitals = VitalsViewModel.buildState(db, keyStore) val inputs = vitals.toCardInputs(units) + // Same accuracy corrections the Today tiles apply (buildState has already applied them to + // the vitals series); each corrected tile is flagged so the widget can say so. + val corrections = com.pulseloop.health.accuracy.AccuracyCorrections.load(db) val metrics = mutableMapOf() for (kind in MetricKind.entries) { val card = VitalsCardFactory.card(kind, inputs, vitals.profile) - var payload = metricPayload(kind, card) + var payload = metricPayload(kind, card).copy(adjusted = when (kind) { + MetricKind.HEART_RATE -> corrections.has(ComparisonMetric.HR_REST) || corrections.has(ComparisonMetric.HR_ACTIVE) + MetricKind.SPO2 -> corrections.has(ComparisonMetric.SPO2) + else -> false + }) if (kind == MetricKind.BLOOD_PRESSURE) { // Same values/zones the Today BP tile reads (offsets already applied in the state). payload = payload.copy( @@ -180,15 +189,16 @@ object WidgetSnapshotPublisher { return WidgetSnapshot( generatedAt = nowMs / 1000L, dayStart = TimeUtil.startOfTodayLocal() / 1000L, - activity = activityPayload(db, units), - sleep = sleepPayload(db), + activity = activityPayload(db, units, corrections), + sleep = sleepPayload(db, corrections), metrics = metrics, ) } /** Replicates the Today activity tile's value derivations (unit conversion, formatting). */ - private suspend fun activityPayload(db: PulseLoopDatabase, units: UnitSystem): WidgetActivityPayload { + private suspend fun activityPayload(db: PulseLoopDatabase, units: UnitSystem, corrections: Corrections): WidgetActivityPayload { val today = try { db.activityDailyDao().byDay(TimeUtil.startOfTodayLocal()) } catch (_: Exception) { null } + ?.let(corrections::day) val goal = try { db.userGoalDao().get() } catch (_: Exception) { null } val steps = today?.steps @@ -206,14 +216,15 @@ object WidgetSnapshotPublisher { stepsText = steps?.let { Formats.count(it) }, distanceText = distanceDisplay?.let { Formats.distance(it) }, caloriesText = calories?.let { Formats.count(it.toInt()) }, + adjusted = corrections.has(ComparisonMetric.STEPS) || corrections.has(ComparisonMetric.DISTANCE), ) } /** Replicates the Today sleep tile's derivations (reference night, stage bar, score). */ - private suspend fun sleepPayload(db: PulseLoopDatabase): WidgetSleepPayload? { + private suspend fun sleepPayload(db: PulseLoopDatabase, corrections: Corrections): WidgetSleepPayload? { val reference = TimeUtil.referenceNightLocal() val night = try { - db.sleepSessionDao().byDay(reference)?.takeIf { it.totalMinutes > 0 } + db.sleepSessionDao().byDay(reference)?.takeIf { it.totalMinutes > 0 }?.let(corrections::sleep) } catch (_: Exception) { null } ?: return null val blocks = try { db.sleepStageBlockDao().forSession(night.id) } catch (_: Exception) { emptyList() } val score = SleepScore.calculate(night, blocks).score @@ -223,6 +234,7 @@ object WidgetSnapshotPublisher { segments = buildSleepStageSegments(blocks).map { WidgetSleepPayload.Segment(it.minutes, colorToHex(it.color), it.label) }, + adjusted = corrections.has(ComparisonMetric.SLEEP_ASLEEP), ) } diff --git a/app/src/main/java/com/pulseloop/widgets/WidgetTileRenderer.kt b/app/src/main/java/com/pulseloop/widgets/WidgetTileRenderer.kt index df7cdd34..0cdf4e49 100644 --- a/app/src/main/java/com/pulseloop/widgets/WidgetTileRenderer.kt +++ b/app/src/main/java/com/pulseloop/widgets/WidgetTileRenderer.kt @@ -113,10 +113,14 @@ class WidgetTileRenderer(private val density: Float) { } else { drawActivityWideContent(canvas, rect, payload) } - // Staleness time in the top-right corner (iOS overlay alignment: .topTrailing). - snapshot?.stalenessEpochSeconds(nowMs)?.let { stale -> + // Staleness time in the top-right corner (iOS overlay alignment: .topTrailing), and the + // accuracy-correction marker beside it (labelled wherever shown). + val corner = listOfNotNull( + ADJUSTED_MARK.takeIf { payload?.adjusted == true && !rolledOver }, + snapshot?.stalenessEpochSeconds(nowMs)?.let(::formatTime), + ).joinToString(" · ").ifEmpty { null } + corner?.let { text -> val p = textPaint(9f, withAlpha(textMuted, 0.8f)) - val text = formatTime(stale) drawTextTop(canvas, text, rect.right - p.measureText(text), rect.top, p) } return bitmap @@ -149,7 +153,14 @@ class WidgetTileRenderer(private val density: Float) { private fun drawMetricTile(canvas: Canvas, rect: RectF, metric: WidgetMetric, snapshot: WidgetSnapshot?, nowMs: Long) { val accent = metric.accentColor.toArgb() val staleText = snapshot?.stalenessEpochSeconds(nowMs)?.let(::formatTime) - val headerH = drawHeader(canvas, rect, metric.headerLabel, accent, staleText) + val adjusted = when (metric.tileStyle) { + WidgetMetric.TileStyle.RINGS -> snapshot?.activity?.adjusted == true + WidgetMetric.TileStyle.SLEEP -> snapshot?.sleep?.adjusted == true + else -> snapshot?.metrics?.get(metric.metricKind?.widgetKey)?.adjusted == true + } + // Accuracy-corrected figures say so, even on a home-screen tile. + val label = if (adjusted) "${metric.headerLabel} · $ADJUSTED_MARK" else metric.headerLabel + val headerH = drawHeader(canvas, rect, label, accent, staleText) val content = RectF(rect.left, rect.top + headerH + dp(8f), rect.right, rect.bottom) val rolledOver = snapshot?.isRolledOver(nowMs) ?: false @@ -607,3 +618,6 @@ class WidgetTileRenderer(private val density: Float) { } } } + +/** Shown on a widget tile whose figures carry an accuracy-check correction. */ +internal const val ADJUSTED_MARK = "adjusted" diff --git a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt index 9bce9ed1..1224a36a 100644 --- a/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt +++ b/app/src/test/java/com/pulseloop/health/accuracy/AccuracyCorrectionsTest.kt @@ -144,4 +144,34 @@ class AccuracyCorrectionsTest { assertEquals("+25 min", AccuracyCorrections.formatValue(ComparisonMetric.SLEEP_ASLEEP, 25.0)) assertEquals("−2.0 points", AccuracyCorrections.formatValue(ComparisonMetric.SPO2, -2.0)) } + + @Test + fun storedReadingsAreCorrectedByKindOnly() { + val corr = Corrections("K", mapOf( + ComparisonMetric.HR_REST to c(ComparisonMetric.HR_REST, -3.0), + ComparisonMetric.SPO2 to c(ComparisonMetric.SPO2, 1.0), + ), age = 40) + fun m(kind: com.pulseloop.ring.MeasurementKind, v: Double) = + com.pulseloop.data.entity.MeasurementEntity(kindRaw = kind.name, value = v, unit = "", timestamp = 0, sourceRaw = "history") + assertEquals(57.0, corr.measurement(m(com.pulseloop.ring.MeasurementKind.HEART_RATE, 60.0)).value, 1e-9) + assertEquals(97.0, corr.measurement(m(com.pulseloop.ring.MeasurementKind.SPO2, 96.0)).value, 1e-9) + assertEquals(45.0, corr.measurement(m(com.pulseloop.ring.MeasurementKind.HRV, 45.0)).value, 1e-9) + } + + @Test + fun theCoachIsToldOnlyWhenSomethingIsAdjusted() { + assertNull(Corrections.NONE.coachNote()) + val note = Corrections("K", mapOf(ComparisonMetric.STEPS to c(ComparisonMetric.STEPS, 1.2))).coachNote()!! + assertTrue(note, note.contains("steps ×1.20")) + assertTrue(note, note.contains("stored readings are unchanged")) + } + + @Test + fun aWidgetSnapshotFromBeforeTheAdjustedFlagStillDecodes() { + val json = kotlinx.serialization.json.Json { ignoreUnknownKeys = true } + val old = """{"generatedAt":1,"dayStart":0,"activity":{"steps":5.0},"sleep":{"durationText":"7h","score":80}}""" + val snap = json.decodeFromString(com.pulseloop.widgets.WidgetSnapshot.serializer(), old) + assertFalse(snap.activity!!.adjusted) + assertFalse(snap.sleep!!.adjusted) + } } diff --git a/docs/accuracy-check-plan.md b/docs/accuracy-check-plan.md index b01d2d7b..e4b25a3f 100644 --- a/docs/accuracy-check-plan.md +++ b/docs/accuracy-check-plan.md @@ -65,10 +65,15 @@ activity" figure either. Bands are editable per metric (slider) and stored on th - A single heart-rate sample's context isn't known at read time, so rest vs active is split at Flex-HR (0.6 × (220 − age)), the calorie estimator's own threshold. - Applied in the ViewModels (Today, Vitals and its detail, Sleep, Activity). The home-screen - widgets share `VitalsViewModel.buildState`, so they show corrected heart rate and SpO₂ too, - but are too small for the caption. Known gap. -- Not applied to: the coach's tools and scores context, the live workout stream, the - Health Connect export, and stored rows. All of these read raw. + widgets get the same corrected steps, distance, sleep, heart rate and SpO₂, and a corrected + tile adds "· adjusted" to its header (each payload carries an `adjusted` flag). +- The coach sees what the app shows: its context builders, summary and notification contexts, + and its data tools all read through the corrections, and its data-quality notes say which + figures are adjusted, so it doesn't present them as raw ring readings or correct them again. +- The live workout readout and its zone are corrected, labelled on the record screen. So are + a finished workout's displayed HR and SpO₂ stats. The samples a workout stores, and its stored + summary, stay raw, because Health Connect and Strava get them. +- Not applied to: the Health Connect export, Strava, and stored rows. - Applied to everything shown while that ring is paired, history included, because stored data carries no ring id. - A steps correction supersedes the existing phone step calibration (`StepCalibration`) on