Gen5 live HR/IMU ownership: separate consumers and serialize transitions

[DropTabl]

Status: approved and implementation-ready

The maintainer verified the races and approved the independent wantHr / wantImu reconciler, including an explicit link-generation guard. This discussion is now the complete implementation contract for the live HR/IMU ownership PR. The final policy and boundaries below supersede the earlier open questions.

The PR may be implemented directly from this body. Optical opcode cleanup, live R-R correction, and the design of a reliable movement-reminder sampling scheduler remain separate concerns; they must not be folded into or used to block the ownership fix.

Why discuss this before a PR?

Edge currently treats a foreground connection as an implicit request for both
realtime HR and the 100 Hz Gen5 IMU stream. Real features need different
combinations, and the existing enable/disable operations can race. The
technical need for explicit ownership is clear, but changing passive step and
movement-reminder behavior is a product decision, so I would like to agree on
the policy before implementing it.

The two related small fixes—Gen5 optical opcode 107/108 cleanup and the live
R-R calculation issue—remain separate from this proposal.

What Edge does today

On Edge main at
d4d4cde:

• openSession()
  unconditionally restores the full live bundle after foreground READY;
• the foreground reconnect path does the same;
• on Gen5,
  enableLiveStreams()
  means opcode 3 HR ON plus opcode 106 IMU ON;
• workouts and breathing also try to restore that same coarse bundle when it
  is off or HR-only; and
• _hasLiveConsumer is a single background-policy boolean. It does not
  represent HR and IMU owners independently.

The streams do have consumers, but foreground connection state is broader than
those consumers and currently hides their different requirements.

Verified consumer map

Feature	HR	IMU	Current use
Visible live-HR view	yes	no	live BPM and short in-memory trace
Any active workout	yes	no	zones, peak HR, strain and calories
Gait workout	yes	yes	live steps and cadence
Non-gait workout	yes	no	no workout-specific IMU output
Current Strength tracker	yes	no	sets/reps/load are manually entered; no IMU inference exists
Breathing session/window	yes	no	R-R for coherence and pre/post RMSSD
Movement/posture reminders	no	yes	foreground movement and wrist-roll observations
Passive foreground strap steps	no	yes	windowed live step spans
iOS background keepalive	yes	no	intentional scheduling/transport strategy in current Edge
History sync and daily derivation	no	no	use historical records, not live frames

The gait list is running, trail_running, walking, hiking,
dog_walking, treadmill and cross_country. All other workouts currently
discard workout step accumulation from the live IMU.

The Gen5 on-chip historical step counter is a whole-day fallback, not the
highest-priority source. Current code uses it only when the resolved windowed
live/phone total is zero:

final useBand = liveStepsReal <= 0 && bandSteps != null && bandSteps > 0;

That distinction matters when deciding whether passive live IMU collection is
worth retaining.

Confirmed transition races

A stale OFF can defeat a new owner

_stopBreathingStreams() starts disableLiveStreams() without awaiting or
tracking it. The engine continues to report liveEnabled == true until the
OFF sequence finishes.

This allows the following order:

1. breathing closes and starts OFF;
2. a workout or new breathing window starts before OFF completes;
3. the new path sees “already enabled” and skips ON;
4. the older OFF completes and leaves the current feature without its stream.

The background downgrade already has a special future/settle mechanism for
this exact race, but breathing teardown is outside it.

The last owner can leave without disabling the stream

Breathing records only whether it happened to perform the original enable. If
it starts while a workout or foreground connection already has streams on, it
records no ownership. When the other feature and then breathing leave, no
single path recomputes the complete remaining owner set. HR and IMU can remain
enabled, with the keepalive continuing to re-arm IMU.

The engine also sets its live flags before enable writes have succeeded. That
is a separate reason the applied state should not double as desired state.

Proposed shape

Use two independently computed desired bits:

wantHr = visibleLiveHrView
      || activeWorkout
      || breathingSessionOrWindow
      || iosBackgroundKeepalive

wantImu = activeGaitWorkout
       || activeMovementReminderSampling
       || passiveStrapStepSamplingOptIn
       || futureExplicitImuConsumer

This represents OFF, HR-only, IMU-only and HR+IMU. A three-state
off / HR-only / full model cannot represent movement reminders without HR and
would unnecessarily arm IMU for breathing and non-gait workouts.

One serialized/coalescing reconciler should:

1. recompute desired HR and IMU from current owners;
2. compare them with applied state for the current BLE link generation;
3. send only the required transition;
4. update applied state only after a successful response;
5. recompute after every await until applied equals desired;
6. ignore stale completions from a replaced link;
7. clear applied state on disconnect while retaining lifecycle-valid intent;
8. reapply current intent after READY instead of hard-coding full live; and
9. keep optical opcodes 107/108 outside this state machine.

Suggested Gen5 policy

Situation	HR	IMU
Ordinary READY with no owner	off	off
Visible live-HR view	on	off
Gait workout	on	on
Non-gait workout	on	off
Current manual Strength tracker	on	off
Breathing session/window	on	off
Active movement-reminder sampling	off	on
Passive foreground step collection	off	off by default
iOS background with no physiological owner	on	off
Android background with no owner	off	off
History sync	off	off

The iOS row preserves Edge's current documented strategy: inbound HR
notifications are intentionally used to make background execution more likely.
This is an Edge platform policy, not a claim of measured guarantee or official
WHOOP parity.

Resolved implementation contract

The maintainer decisions are final for this ownership PR:

1. Passive foreground steps: OFF by default on Gen5. An ordinary foreground connection is not an IMU owner. A future explicit opt-in may request IMU through the same reconciler.
2. Movement reminders: never hold IMU merely because the preference is enabled. The reconciler must expose a temporary, IMU-only activeMovementReminderSampling owner for bounded sample windows. The window scheduler is not part of this PR: sampling only inside bounded windows cannot prove that movement did not happen between them, so this PR must not invent a cadence or make a new uninterrupted-stillness claim. Until a separately validated scheduler can observe the gaps, no standing movement-reminder IMU owner is created.
3. Strength: HR-only while sets, reps and load remain manually entered. Do not arm unused IMU to imitate the official app.
4. Background gait workouts: HR remains owned by the active workout, but IMU is not promised in background until measured delivery is shown to sustain the pedometer sample-rate floor. Foreground gait owns HR+IMU. Background gait validation is a follow-up, not a blocker for this PR.

Required ownership model

Compute desired state from explicit consumers, never from foreground connection state:

wantHr = visibleLiveHrView
      || activeWorkout
      || breathingSessionOrWindow
      || iosBackgroundKeepalive

wantImu = foregroundActiveGaitWorkout
       || activeMovementReminderSampling
       || passiveStrapStepSamplingOptIn
       || futureExplicitImuConsumer

activeMovementReminderSampling and passiveStrapStepSamplingOptIn default to false. The model must represent all four states: OFF, HR-only, IMU-only and HR+IMU.

Required transition semantics

• One serialized/coalescing reconciler is the only writer of HR opcode 3 and Gen5 IMU opcode 106 state.
• Desired and applied state are separate.
• Applied state changes only after a successful write/response.
• After every await, recompute desired state and continue until applied equals the newest desired state.
• Bind applied state and in-flight completions to the active BLE link generation; stale completions cannot mutate a replacement link.
• On disconnect, clear applied state but retain only lifecycle-valid intent. After READY, reapply current intent instead of hard-coding full live.
• A failed transition remains retryable and must not be reported as applied.
• Removing one owner must not disable a stream still requested by another owner.
• History sync is never a live HR or IMU owner.
• This state machine must not write optical opcodes 107 or 108.
• Existing Gen4 wire behavior must remain unchanged.

Required acceptance tests for this PR

Use delayed and failing fake writes to cover:

• ordinary Gen5 READY with no owner: no opcode 3 or 106;
• live-HR view and breathing: HR-only;
• foreground gait workout: HR+IMU;
• non-gait workout and current Strength: HR-only;
• active bounded movement-sampling window: IMU-only; outside the window: no movement-reminder owner;
• overlapping workout/breathing: HR remains until the final HR owner leaves;
• close/reopen during delayed OFF: final state matches the new owner;
• failed ON: applied state remains off and can be retried;
• disconnect during transition: stale completion cannot mutate the new link;
• reconnect: current desired owners are reapplied;
• background gait workout: HR remains requested, IMU is off pending measured sample-rate validation;
• Android background with no owner: OFF;
• iOS background with no other owner: HR-only;
• no HR/IMU transition writes opcode 107 or 108;
• ordinary foreground READY and history sync create no HR/IMU owner;
• rapid owner changes during delayed writes converge to the newest desired state;
• two HR owners overlap: HR turns off only after the last owner leaves;
• two IMU owners overlap: IMU turns off only after the last owner leaves; and
• existing Gen4 command sequences remain unchanged.

Non-goals

• The Gen5 optical 107/108 cleanup.
• The live R-R timestamp/adjacency calculation fix.
• Realtime wearing-byte semantics.
• Changes to historical sleep, recovery, HRV, stress or respiration.
• A quantified battery-saving claim; this proposal has not measured one.
• Claiming that the proposed Edge policy exactly matches the official app.

[abdulsaheel]

going through this now — verified the races, they're real (and stopWorkout is actually worse than you said, it never calls disableLiveStreams at all right now, nothing recomputes owners when a workout ends).

my calls on the 4:

1. passive foreground steps — default off. daily counter covers the fallback, not worth holding IMU open all the time for it. can revisit as opt-in if people actually ask.
2. movement reminders — bounded sampling, not whole-session IMU. it's a 2hr-stillness check, doesn't need to hold the stream open that whole time. just make sure the duty cycle can't miss a real movement between windows.
3. strength — HR-only for now. don't arm IMU just to mirror the official app's sequence when nothing reads it yet.
4. background gait — hold off on "keep both desired" as a given. want to actually measure whether the background link holds the sample rate the pedometer needs before we bake that in as policy. if it doesn't, we'd just be shipping quiet zero-step bugs.

architecture-wise: wantHr/wantImu reconciler is the right shape, matches how ble_state.dart/sync_policy.dart already work (pure policy class, diff desired vs applied). one thing to add — needs a link-generation id so a stale completion from a replaced connection can't stomp the current one. we already do that informally in a couple places, just make it explicit here. go ahead and build it.