Effort: one resolved figure for every read-out on Today (#1001)

[ryanbr]

Fixes #1001.

Reported as Effort disagreeing with itself on Today: the hero ring read 2.3 while the Key Metrics tile and the HR chart's edge badge both read 0.5.

What was wrong

Effort has two sources. The stored DailyMetric.strain is rewritten only when the heavy daily pass runs; the live in-progress value recomputes today's HR from local midnight to now, and exists precisely because the stored row lags (#402).

Only the hero ring knew about the live value. The tile and the chart badge read the stored column directly. The reporter's HR trace climbs from about 09:00 with the screenshot taken at 12:22, so the row predated the entire morning — the ring counted it, the other two did not.

Recovery and Rest matched across all their read-outs precisely because neither has a live path. That asymmetry is what made the diagnosis unambiguous.

Not a 9.3.0 regression, though it surfaced there. The live hero landed in v4.0.1 on 15 June; the tile has read the stored column unchanged since 14 June. #963 made Effort track an active morning more closely, which widened the gap against a stale row until it became visible — the same change the reporter credits for Effort behaving better.

The fix

StrainScorer.effectiveEffort(live:stored:) is now the single rule, Swift and Kotlin, with twin test suites.

The max in it is not a tie-break. Effort accrues over a day and must never visibly drop; the live recompute can under-read when HR is sparse or a logged workout's load isn't in the raw stream — #489/#506 had a 5/MG user's real 38.3 replaced by a live 0. Worth naming explicitly, because preferring live is exactly what someone would "simplify" this into later.

Android resolves once in TodayScreen and threads it to MetricGrid and HeartRateTrendCard, alongside the resolved values those already accept (caloriesForDay, importedStepsForDay). The near-zero Effort caption turned out to hold a fourth hand-rolled copy of the same expression — it now uses the shared one, and still returns null for past days so the caption stays today-only.

iOS already had effortStrain() as its single point, and its gauge and near-zero note used it — but effortMarker and the Effort StatTile reached past it to the row. Both now resolve through it, and it delegates to the shared rule so the platforms cannot drift.

Verification

• 7 new tests per platform, same cases in the same order. The Kotlin suite runs green locally against the function extracted verbatim from source: OK (7 tests). The Swift twin runs in swift-packages CI (StrandAnalytics needs macOS here).
• Cases: live ahead of a stale row, the Import FIT activity steps #489/Restore recognizable Android dashboard metric icons #506 floor, past-day (no live), pre-score (no row), both-nil staying "No Data", a genuine zero surviving as a value rather than an absence, and equal sources being stable.
• Kotlin: full src/main/java compile — 2517 errors on this branch and 2517 on main, 126 in TodayScreen.kt on both. No new errors.
• swiftc -parse clean on TodayView.swift, StrainScorer.swift and the new Swift test.
• Tools/doc_comment_lint.py and Tools/i18n_audit.py --ci both clean.

app-build.yml is disabled, so nothing compiles the iOS/macOS app target — the TodayView.swift edits are parse-checked only and want an app build before this is relied on. The shared rule and its Swift tests are covered by swift-packages.

Re-review

No new defects. What the pass added:

Verified rather than asserted. The earlier "same error count" claim is now a set comparison: the branch and main produce byte-identical Kotlin error sets, so nothing new is hiding behind an equal total. MetricGrid has exactly one call site. On iOS, effortStrain, effortMarker and keyMetricTile are all inside struct TodayView (opens line 171, no top-level close before them), so the helper is in scope at both new call sites — and keyMetricTile already opens with let d = displayDay, making the let effort = … I added the same construct that function already uses. That matters because app-build.yml is disabled and nothing compiles this file.

The chart fix reaches further than the badge. strain feeds four Effort read-outs in OverviewHRChart: the marker's visibility gate, its colour, its label, and the accessibility description, which announced "0.5 Effort now" while the ring showed 2.3. Screen-reader output was wrong in the same way and is fixed by the same change.

Known limit, deliberately not changed. The Effort tile's 14-day sparkline still comes from the stored daily series, so on today it ends at the stored value while the number above it shows the resolved one. On a 0–100 axis in a sparkline that height the difference is around 2% of range — not visible, and substituting the last point means reaching into a shared Window used by other tiles. Recovery and Rest are unaffected because neither has a live path. Left as-is, recorded here rather than discovered later.