Report what each offload burst actually achieved (#1007)

[ryanbr]

Diagnostic only, from #1007. No BLE op, no timing change, no default flipped.

The gap

History offload is the dominant battery cost — #1007 measured ~2.4 h of radio a day on a WHOOP 4.0 and ~41 min on a 5/MG, against the official app doing 24 h in 1–3 minutes.

Two levers that attack exactly that are already written and tested:

• [ble] Battery: GATT connection-priority management (HIGH during offload/live, opt-in LOW_POWER idle) — Android #477 — CONNECTION_PRIORITY_HIGH for the bounded offload burst. HIGH is a shorter interval, so it cannot cause a supervision-timeout drop; it shortens the radio-on window.
• Fast historical sync: HCI capture of the official app's bulk-offload command #533 — LE 2M PHY around the same burst.

Both ship off, gated on a real-strap before/after. That validation has never happened, and the reason is visible in the code: nothing measures the thing they change. onPhyUpdate's own comment already talks about a log showing "the negotiated PHY next to the offload's records/sec" — but no records/sec is computed anywhere. #1007's figures had to be counted by hand out of a raw capture (3193 frames / 90 s), which is not something a reporter can be asked to do twice.

What changes

exitBackfilling logs what the burst achieved, beside the exit reason it already classifies:

Backfill: 3193 frame(s) in 90.0s (35.5 frame/s) (HISTORY_COMPLETE)

Validating #477 or #533 becomes toggle → sync → compare two lines.

Unconditional, and one line per offload rather than per frame. Behind TestDomain.CONNECTION a reporter would have to find Test Centre first — that friction is part of why these levers are still unvalidated after two issues. One line per burst costs nothing.

Frames, not records. offloadFramesThisSession counts genuine offload frames (47/48/49/50) — what the levers actually move, and the same numerator #1007 measured, so the new line is directly comparable to the figures already in that issue.

A non-positive elapsed reports the count with no rate, never a fabricated one.

Deliberately not included

Neither default is flipped. "A shorter interval is strictly safer" is a plausible argument, not a measurement — and this is BLE code with hardware-learned hazards (#85/#50, #241). This PR is what lets that argument become a measurement; flipping on the strength of the argument alone is the mistake.

Android only. The levers being validated have no CoreBluetooth equivalent — iOS cannot set connection priority at all, which #477 records as a deliberate platform divergence rather than a parity gap. Adding an unused metric to app-target Swift that CI does not compile would be surface without a purpose. Easy follow-up if the throughput figure is wanted on iOS as a general diagnostic.

Re-review: the first cut missed the interrupted burst

exitBackfilling has exactly three call sites — HISTORY_COMPLETE, timeout and aborted by user. A burst cut short by a disconnect goes through reset() instead, which clears backfilling and zeroes the frame counter without passing through any of them. So the metric silently skipped it.

That absence is ambiguous in exactly the wrong way for a battery question: "no offload happened" and "an offload was cut off" looked identical in the log, and they are opposite findings — the interrupted one spent radio and banked nothing.

Now logged from reset() as (interrupted). Deliberately not by calling exitBackfilling there: that method also releases the connection priority and the PHY and records a sync outcome, none of which the teardown path does today, so routing through it would turn a diagnostic into a behaviour change. Guarded on backfilling, so a burst that already logged on its way through exitBackfilling cannot log twice.

The one remaining bypass is deliberate: onBackfillTimeout's 5/MG zero-frame retry clears backfilling directly, but it already logs no history frames arrived — retrying request, so a 0 frame(s) line beside it would only repeat what that says.

Verification

• 5 tests green locally against the helper extracted verbatim from source: History offload costs 41 min (5/MG) to 2.4 h (4.0) of radio per day; the official app does 24 h in 1–3 min #1007's own 3193/90 s case (which reproduces its 35.5 frame/s exactly), the 4.0's ~10 frame/s, a strap that sent nothing, an unknown elapsed, and a sub-second burst.
• Tools/doc_comment_lint.py and Tools/i18n_audit.py --ci main clean.
• backfillStartedAtMs is its own field rather than a reuse of lastBackfillAtMs, which is the BackfillPolicy floor and measures from the last kick.
• exitBackfilling early-returns unless backfilling, which only enterBackfilling sets — and that is where the stamp is taken, so the elapsed cannot span two bursts.