Count the packet types a history offload drops, instead of dropping them silently (#891)

[ryanbr]

Read-only. No new opcode, no hardware write, no storage, no strings.

The gap

A history offload silently discards any packet type the decoder has no case for:

• extractHistoricalStreams switches on four of the schema's sixteen packet types and
  default: continues the rest — no counter, no log.
• rejectedHistoricalRecords will not catch it either. It is gated frame[typeIndex] == 47, and its
  own comment says non-47 types "never pass this gate — they are excluded by construction".

So an unmapped record is dropped twice and counted zero times, and the sync reports clean.

Not hypothetical: HISTORICAL_IMU_DATA_STREAM(52) is a banked raw-stream type our own schema
already names and this funnel does not handle. Every one would vanish.

Why now

#891's leading hypothesis (b) is that the 5/MG banks Labrador ECG to flash rather than streaming it,
and the open ask is "has anyone seen an unrecognised record type or buffer type in a 5/MG offload?"

Nobody can answer that today. There is no instrument that would show one, so running the
experiment cannot produce a finding in either direction — a negative would be indistinguishable from
not looking. This is the instrument.

It is worth having regardless of how #891 resolves: any future firmware record type is invisible right
now, on both platforms.

What it does

Streams.unhandledPacketTypes / StreamBatch.unhandledPacketTypes census the types that fall through,
keyed by rendered name. The Backfiller logs each the first time it appears — a 30k-record offload
must not emit 30k lines — naming the type and asking for a report on #891 if it is unfamiliar.

Transient diagnostics exactly like droppedImplausible, whose pattern this follows: not persisted, not
in CodingKeys, excluded from isEmpty, empty by default so golden fixtures stay byte-identical.

METADATA and CONSOLE_LOGS are excluded. An offload legitimately carries both and they decode to
zero rows by design; counting them would put a scary line in every strap log and train people to ignore
the one that matters. Named-but-unhandled types are not excluded — those are the interesting ones.
The exclusion set is pinned by a test on both platforms, because quietly adding to it is how this stops
reporting the thing it was built for.

Two parity defects found while writing it

• PacketType 53-56 were missing from the Kotlin enum, so the same byte would render type53 on
  Android and RELATIVE_PUFFIN_EVENTS on Apple — one strap, two different report lines in a diagnostic
  meant to be pasted into an issue. Added as decode-only names; nothing dispatches on them.
• The rendering has to be family-aware, and was not. Swift renders a WHOOP 4.0 frame through
  schema.typeName (no aliasing) and a 5/MG frame through canonicalTypeName; the Kotlin census always
  aliased. A 4.0 frame of type 56 would have been counted as PUFFIN_METADATA on Apple and silently
  excluded as METADATA on Android — the two platforms disagreeing about an anomalous frame, which is
  the single case this exists for. Kotlin now picks the rendering by family, and both suites pin it.
• Kotlin dispatches on the raw type byte before any CRC check, where Swift skips CRC-failed frames
  before its switch. Left alone, a corrupt frame would have been reported as an unknown firmware feature
  on Android and not on Apple. The Kotlin branch now checks CRC explicitly — a CRC failure is a
  different finding with its own archive.

Framing.typeName went private -> internal so both the census and the frame labeller render through
one copy of the aliasing rules rather than two that can drift.

Verification

• New tests both sides, 1:1: named-but-unhandled counted, unmapped byte counted under its rendered name,
  distinct types tallied separately, METADATA/CONSOLE_LOGS not counted, the exclusion set pinned, a
  normal offload producing an empty census, a CRC-failed frame not counted, the census absent from the
  Codable path, both puffin types keeping their own names on 4.0, and packet-type names matching across
  platforms byte for byte.
• One end-to-end case per platform, through the real parser. The rest hand-build a decoded frame, which
  assumes the thing most likely to be wrong: the decoder skips not-ok frames BEFORE its switch, so if the
  parser marked an unmapped type not-ok the census would never fire and every other assertion would still
  pass. Writing that test found a second defect — both builders declared the envelope length as the inner
  record alone, where it covers the record PLUS the 4-byte CRC32 trailer, so the parser could not locate the
  trailer and never verified. Kotlin passed anyway (crcOk null, not false); Swift caught it. Both fixed.
• Tools/doc_comment_lint.py clean.
• Kotlin: HistoricalStreams.kt, Enums.kt and Framing.kt compile clean locally (Gradle itself does
  not run on this arm64 host — aapt2 is x86-64 only — so this was the embeddable compiler over the
  protocol + data packages; remaining errors in that partial compile are packages I did not pass it).
  Android CI is the real gate.
• Strand/Collect/Backfiller.swift is app-target Swift, which nothing compiles while app-build.yml
  is disabled. The package half is covered by swift-packages. The Backfiller hunk is a for over a
  dictionary and a log call, but it is uncompiled and I would rather say so.
• No hardware: this changes what a decode REPORTS, not what is sent. Nothing was run against a strap.

Where it is surfaced, and where it is not

Verified reachable rather than assumed: there is no early return between decode and the log on either
platform, which matters because a chunk of ONLY unmapped records has isEmpty == true and an
empty-chunk shortcut would have made this inert in exactly the case it exists for. Both log sinks are
wired in production (BLEManager / WhoopBleClient), so the line reaches the strap log a user can paste.

Not surfaced on Android's capture-replay path. CaptureImporter calls the same decoder, so the
census is computed and sits on the StreamBatch, but that caller does not log it. The #891 experiment is
a live offload, so the path that matters is covered — noting it rather than leaving it to be discovered.

One judgement call worth flagging

RELATIVE_BATTERY_PACK_CONSOLE_LOGS(55) is left in the census rather than excluded with the other
console type. If it turns out a 5/MG carries it routinely in an offload, it becomes noise and wants a
one-line addition to the exclusion set — but there is no evidence in-tree that it appears at all, and
over-reporting once is recoverable in a way that never reporting is not.

Refs #891.