ecg: 124's argument mapping is inverted on hardware — 2 starts generation, 1 stops it, 0 is refused

[Zebsi235]

What this PR does

Whoop5Ecg.ControlSignal maps mainControlECGDataGeneration's argument as stop = 0 / start = 1 / restart = 2. That reading came from the vendor client's enum declaration order and shipped explicitly unverified in #896. On a WHOOP MG it is wrong.

Each argument sent on its own, watching the type-43 stream rather than the ack, across two sessions on 2026-08-28:

arg	shipped name	ACK	observed
0	stop	FAILURE(0) ×10	refused, generation unchanged
1	start	SUCCESS(1) ×20	stops generation
2	restart	SUCCESS(1) ×20	starts generation

Three things back that up beyond the ack counts.

An isolation test. With TOGGLE_LABRADOR_FILTERED(139) closed, 124 = 2 was sent three times on its own with a 30 s listen each: zero type-43 packets. Then 139 = 1 followed by 124 = 2 and the stream returned within 10 s. Three negative controls, one positive, one variable.

A 10-cycle automated run. A reliability pass alternating the two arguments 5 s apart, scoring each window: startFlat=10/10, restartActive=9/10. The argument the shipped enum calls start produced a flat stream in all ten cycles.

The strap's own firmware. Its CONSOLE_LOGS narrate the analog front end, and NOOP already mirrors those into the strap log:

27, 81488729: MAX86176: Set ECG ON

That line appears once per 124 = 2, eight sends and eight lines. The console carries the strap's own uptime, so the correlation does not depend on my clock: the seven gaps between sends match the seven between firmware events to within 0.2 s.

That last one also sharpens what 139 does, and the doc comment says so rather than repeating the older reading: Set ECG ON fires whether or not 139 is open, so 139 gates the stream, not the front end. Detail on #891.

The load-bearing part is not the label

requestsRealtimeData accepted both 1 and 2:

arg == ControlSignal.START.raw || arg == ControlSignal.RESTART.raw

arg == 1 returned true. But 124 = 1 stops generation, so it asks for nothing. A run whose last act was to stop the stream was scored as having requested realtime data, and Whoop5EcgProbe's "acknowledged and then not honoured" verdict could fire on silence the run itself caused. The predicate's own doc states the intent it was failing to deliver: "A run built only from such commands has asked for nothing, and its silence is the expected outcome rather than a finding." The fail-safe design was intact; it was fed a wrong ordinal.

Shape of the change

• The enum carries the hardware values, with device and firmware named in the doc block and the single-device limit stated, mirroring how WristSelection right above it already flags its inference.
• RESTART is gone rather than renumbered. 0 is refused by the strap, so there is no third case to name, and nothing can send a value the strap rejects.
• requestsRealtimeData accepts only START.
• docs/PROTOCOL.md and ATTRIBUTION.md updated. ATTRIBUTION previously said no strap had been asked whether it honours these commands, which is no longer true.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• CI / tooling

How it was tested

On hardware. WHOOP MG, hw WS50_r00, fw 50.39.1.0 (DIS-attested this session), no subscription, Pixel 9 Pro / Android 15, on a local build with per-command logging so each argument could be sent alone and the stream watched instead of the ack. Two capture sessions, 2026-08-28 22:02 and 22:33.

Android unit tests, full suite, ./gradlew testFullDebugUnitTest --rerun-tasks --no-build-cache on Windows 11 / JDK 17 against main @ 911a02c: 4,761 tests across 584 classes, 0 failures, 0 errors (6 skipped, pre-existing).

Fail-then-pass, --tests "com.noop.protocol.Whoop5Ecg*":

• with the fix: 58 tests, 0 failures
• with the enum reverted to STOP(0) / START(1) and the tests kept: 4 failed — commandPayloadIsRevisionThenArg, everyCommandFrameBuilderMatchesItsOpcodeAndArg, onlyTheStreamAndGenerationVerbsCanProduceRealtimeData, attestedResultCodesOutrankTheShapeHeuristic
• fix restored: 58 tests, 0 failures

The tests now assert literal wire bytes alongside the symbol, on both platforms. The previous cases asserted through ControlSignal.X.raw, so they moved with the enum and stayed green whatever the argument meant on the wire, which is exactly how this survived. Two of the four failures above are in that category and could not have failed before.

One existing test needed its fixture corrected, and it is worth naming because it shows how the wrong mapping was pinned: attestedResultCodesOutrankTheShapeHeuristic built its "the data request was refused" case as sent(124, 1, Failure). Under the corrected mapping 124 = 1 requests nothing, so the fixture became sent(124, 2, …). The test encoded the assumption.

python Tools/doc_comment_lint.py clean.

Not run: swift test. No Apple machine here, so the Swift half is compile-unverified by me and left to swift-packages.yml, which covers Packages/**. The Swift edits mirror the Kotlin ones line for line and the Kotlin twins pass, but that is reasoning rather than a compile. Same for CLAUDE.md's oracle rule: I could not run swiftc to generate the expected literals.

What this does NOT claim

• One device, one firmware. ECG negative result: the 1584-byte flash record is layout v16, and it is empty with the circuit closed #1100 ran WS50_r03 / 50.40.1.0 and nothing here says the two agree.
• Whether 2 is a plain start or a stop-then-start is not distinguishable from a stream already off, so the case is named for what it achieves rather than for the client's third name.
• Nothing about the waveform's unit or scale.
• This does not close ECG negative result: the 1584-byte flash record is layout v16, and it is empty with the circuit closed #1100. The 1584-byte v16 flash records stayed empty here too, throughout a run that was streaming live. That null stands.
• It does not explain every SUCCESS-with-silence run, only supplies one mechanism that fits them.

Checklist

• Swift package tests pass — not run locally (no Apple machine); left to swift-packages.yml
• Android unit tests pass (./gradlew testFullDebugUnitTest, full suite)
• No new build warnings introduced
• UI changes use only StrandDesign tokens — n/a
• No hardcoded hex frame bytes; protocol facts live in the schema / decoders
• Follows the conventions in docs/CONTRIBUTING.md
• I did not commit generated output or any secrets/keystores

Related issues

Refs #891, #1100, #896, #1103.

Does not close any of them — see "What this does NOT claim".

[Zebsi235]

CI caught the gap I declared: testOffPathIsTheExactInverseOfTheOnPath is Swift-only with no Kotlin twin, so my Android runs could not reach it. It pinned all three OFF frames to arg 0, written from the old enum-order mapping. Fixed in a9ea638: the generation stop now expects arg 1 (0 is refused on hardware), the two toggles still turn off with 0, and the comment says why the three are no longer uniform.

Nothing else in the Swift suite references the old values; I swept the package tests and the app-target senders, which all go through the enum symbols.