WHOOP 5/MG: passive optical-block phase experiment (harness for #858, on top of #546)

[vishk23]

#546 gave the 2,140-byte layout-v20 record a neutral structure: five repeated 422-byte blocks, each with a 21-byte header, two 200-byte readout slots and a reserved byte, with sample counts that are always [25, 0, 0, 25, 25] in the existing corpus. Structure, deliberately without names — no block is called red, IR, green or ambient, because nothing in the bytes says so.

This adds the harness that could earn those names: a passive experiment that marks physical phases on the phone and compares what each block does across them, offline. It is the thing #858 asks a capture for and the thing #845 says the v18/v20 fields are missing.

What it does

Phase marking (app). Settings → Advanced → Experimental · WHOOP 5/MG gains "Mark phase…" and "Export experiment…", shown only when frame recording is already on. A marker appends one line to the existing puffin-deepbuffers.jsonl:

{"kind":"optical_phase","label":"off_wrist_dark","unix_ts":…,"ts_ms":…}

Eight fixed phases: on-wrist still, gentle pressure, off-wrist covered, off-wrist room light, on-wrist again, slow paced breathing, normal breathing, end.

Offline analysis (whoop-optical-experiment CLI + OpticalExperimentAnalysis). Reads that JSONL back, attributes each v20 frame to a phase, and emits JSON: per-phase block activation, per-header-byte behaviour, per-channel ADC statistics, and adjacent-phase deltas.

Docs. docs/WHOOP5_OPTICAL_EXPERIMENT.md — the capture procedure, the timestamp model, and what the output does and does not license you to conclude.

The two design decisions that matter

It sends nothing to the strap. markWhoop5OpticalPhase reaches PuffinDeepBufferLog.appendOpticalPhase, which is a file append. There is no peripheral, no characteristic, no command path — not a read, not a write. The BLE safety contract is not merely respected here, it is structurally unreachable. This also means the harness needs no new permission, changes no connection behaviour, and cannot affect scoring.

Attribution uses the strap's timestamp, not arrival time. Deep buffers arrive during the connect-time offload burst, often minutes after the seconds they describe. Bucketing by log-arrival time would smear every phase into its neighbours. The analyzer compares the marker's phone Unix time against the Unix timestamp inside each v20 frame. The CLI also drops the first 10 s after each marker by default (--settling-seconds, 0 keeps everything), so putting the strap on, taking it off, covering it and pressing it stay out of the steady-state summaries.

What it deliberately does not do

It does not assign a wavelength to any block, and it does not compute SpO₂ or blood pressure. Per the repo's rule on deriving a physiological signal from raw sensor data, an experiment that produced one matching number would prove nothing; the questions here are narrower and answerable:

• Which blocks respond to wrist contact, darkness, room light, pressure, paced breathing?
• Do blocks 1 and 2 — configured but showing 0 samples in every record so far — ever acquire?
• Which of the 21 header bytes move with which physical condition?
• Do the two readout slots inside one block behave as paired detectors of one measurement (rather than as two separate measurements)?

Those are the questions that have to be settled before anyone can honestly claim a wavelength, let alone a saturation.

Verification

Packages/WhoopProtocol  swift build                      Build complete
Packages/WhoopProtocol  swift test                       343 tests, 0 failures   (184 new lines of tests)
macOS app               xcodebuild -scheme Strand build  ** BUILD SUCCEEDED **
macOS app               xcodebuild -scheme Strand test   959 tests, 1 skipped, 0 failures
                        python3 Tools/i18n_audit.py --ci  pass
                        python3 Tools/doc_comment_lint.py pass (no new detached doc comments)

The app-target half (BLEManager, SettingsView, PuffinDeepBufferLog) is compiled and tested locally, since app-build.yml is disabled by default.

Not validated on hardware in this PR, and it cannot be: the harness exists precisely because nobody has a labelled capture yet. The BLE surface it adds is a file append, so there is no connection behaviour to test on a strap.

Cross-platform parity

Swift only, on purpose. The parity contract binds analytics and stored values; this stores no analytics and changes no scored number. The capture side (PuffinDeepBufferLog, PuffinFrameRecorder, the whole R22 deep-buffer lane from #423) has no Android counterpart at all, so there is nothing on Android for a marker to mark or an analyzer to read. If the deep-buffer lane is ever ported, the phase marker is ~30 lines of file append and this doc + CLI apply unchanged — the JSONL and the report format are the contract, not the Swift.

Two small commits on top of the harness

• i18n: the four new user-facing strings were English-only, which Tools/i18n_audit.py --ci hard-fails. Translated into de/es/fr/pt-PT (zero-tolerance focus locales) and it/ru/zh-Hans/zh-Hant (each of which would otherwise have gone 4 over its ratcheting allowance). Appended textually so the other 3,255 catalog entries keep their bytes and their order.
• docs: the status line named a private fork branch nobody can resolve, and implied a result where there is only a harness. Points at [ble] WHOOP 5/MG raw accel/IMU: community-verified live 0x2B raw-accel stream (cmd 81) that the 5/MG allowlist never arms — gated probe + decode proposal #423/Capture wanted: paired v18 + deep-buffer overnight, and a timed strap-loosening run, to settle the v18 optical/quality fields #858/v18: 23 of 33 decoded fields have no downstream consumer — inventory, and what should read them #845 instead and says plainly that no labelled run has been analysed yet.

Related: #423, #858, #845. Builds directly on #546.

[ryanbr]

Careful work, and unusually well-disciplined about what it refuses to claim. Verified the load-bearing parts rather than taking them:

"It sends nothing to the strap" holds structurally. markWhoop5OpticalPhase → PuffinDeepBufferLog.appendOpticalPhase → try append(line + "\n"). No peripheral, no characteristic, no command path anywhere on that route. As you say, the BLE safety contract is not respected here so much as unreachable, which is the right shape for an experiment harness.

Timestamp attribution is right, including the part that is easy to get wrong. experiment_end is excluded from phases but retained in markers, so it bounds the final phase without becoming one — and endUnixTs indexes the full marker list while phaseIndex searches only real phases. Those two could easily have drifted apart; they have not. The frame.baseTs == strapTs gate as a consistency check on the envelope rather than a substitute for frame content is also the correct instinct.

The CLI really does default to 10 s settling (var settlingSeconds = 10), matching the description, while the library defaults to 0 — the right split, since a library should not silently discard data.

On i18n: thank you for doing it properly. #850 landed a few hours ago and made it/ru/zh-Hans/zh-Hant gate against a ratcheting allowance. You translated all four new strings into all eight locales and left i18n_extra_locale_baseline.txt untouched. Raising the allowance would have passed CI just as green; you did the thing the gate exists to encourage, on its first day. That is worth saying out loud.

Parity reasoning accepted. The deep-buffer lane has no Android counterpart, so there is nothing on that side for a marker to mark. Stating that the JSONL and report format are the contract — not the Swift — is the right way to leave it portable.

10/10 green. The only thing I would flag is not a defect: this is a harness whose value is entirely in the capture nobody has taken yet. Worth being explicit in #858 about who is expected to run it and on which strap, so it does not sit as unexercised machinery.

No changes requested.