burst_index and layout_marker are decoded and then destroyed — the only two decoder fields with no banked home (extends #845 to v26/v20-21) #979

burst_index (v26) and layout_marker (v20/21) are decoded on every matching frame, persisted nowhere, and not reconstructable from anything that is persisted — so they're destroyed when the strap frees history on offload-ack.

This is the same argument #845 makes for the v18 fields, applied to the two frame families #845 doesn't cover. I checked all 44 keys the Interpreter emits into parsed against every production consumer on both platforms; these are the only two with no banked home.

Why these two are different from the other unread fields

Most unread decoder output is recoverable, which is why it's fine:

These two aren't:

• burst_index — Interpreter.swift:609, fb.add(21, 1, "burst_index", "ppg", …). v26 isn't v18, so there's no V18AuxSlot for it, and ppgWaveformSample stores only (ts, samples). Production readers: 0. Only references are Whoop5PpgWaveformTests.swift:49,70.
• layout_marker — Interpreter.swift:666, fb.add(10, 1, "layout_marker", "meta", …). The v20/v21 layout discriminator (0x80 vs 0x81 in the fixtures). Production readers: 0. Only references are Whoop5HistoricalV2021Tests.swift:67,131,159.

Both surface in the whoop-decode CLI, which iterates parsed.fields (Packages/WhoopProtocol/Sources/whoop-decode/main.swift:211) — useful for inspecting a capture you already have, but it doesn't make the app's path live.

Parity note

Neither has a Kotlin twin. burst_index appears in android/.../protocol/HistoricalStreams.kt:459 only inside a comment explaining what @21 is; nothing decodes it. layout_marker has no Kotlin reference at all. So a v26/v20 capture from an Android user is missing both fields even in the frame inspector.

Why it might be worth two lines

burst_index is the per-burst counter (PR#553) — the thing that tells you whether two v26 frames belong to the same 40 s burst or different ones. Whoop5PpgWaveformTests.swift:56 uses exactly that to distinguish two bursts ~19 min apart. Any future work over ppgWaveformSample (a better HR estimator, HRV-from-PPG — the reasons Database.swift:592-606 gives for keeping those rows at all) has to segment by burst, and right now the rows it would run over don't carry the burst boundary. That seems like the one field where "we kept the samples but dropped the thing that groups them" actually bites.

layout_marker is cheaper to argue about — one byte, and the layout is re-derivable from the frame if you still have the frame. But you don't: the strap frees it.

Suggested fix

Either add two slots alongside the existing aux banking, or drop them from the decoder so the inventory in #845 stays honest about what's kept. I'd do burst_index and leave layout_marker, but I don't have a strong view. Happy to send a PR for whichever.

Two small things noticed alongside, not worth their own issues:

• Packages/WhoopProtocol/Tests/WhoopProtocolTests/DeepCaptureChannelsTests.swift:285-292 names its set persistedElsewhere and asserts each slot "already has a durable home". That's not true for spo2_candidate_82 or motion_wear_quality — both are derivable from a banked byte, neither is persisted. The behaviour is right, only the label overstates; it briefly convinced me SpO2 was being stored. recoverableFromABankedField would read truer.
• Tools/ and tools/ are two distinct trees at the repo root (git ls-tree main Tools/linux-capture/ returns nothing; the linux-capture files are under lowercase tools/). On a case-insensitive macOS checkout they merge into one visible directory, so a macOS contributor can add a file to what they see as Tools/linux-capture/ and have it recorded under the other tree. Nothing is broken today — docs consistently say lowercase — but it's a trap worth a normalization commit.

Environment: fork of main at af44563c; all file:line refs against that tree.