perf(decode): fast-path 1/2-byte varints (+12% codec decode)

[facontidavide]

Summary

decodeVarint is the hottest primitive on the decode path (~8 calls per point for a typical LIDAR cloud). It ran a general loop with a per-byte bounds check and two overflow checks for every value. This PR adds branch-predicted 1-byte and 2-byte fast paths — covering the vast majority of real deltas — while keeping the careful general path for 3+ byte varints and all truncation/overflow/NaN semantics unchanged.

The motivation came from profiling decode with perf: after a stage of decodeVarint calls dominate both the integer fields and the inlined XYZ float path, the redundant per-byte checks were a measurable tax.

Results (codec-only decode, DATA/ouster_os1.mcap, 94 msgs)

Mode	Before	After	Δ
V4	~1462 MB/s	~1643 MB/s	+12.4%
V5	~1303 MB/s	~1464 MB/s	+12.4%

Measured with mcap_codec_benchmark --decode-replay --mode <V4/V5> --decode-repeat 40 (5 runs each, tight ±0.5% variance). The general (3+ byte) path is the original code byte-for-byte; only the 1- and 2-byte paths are new.

Correctness

• New differential test DecodeVarintMatchesOracleExhaustiveAndRandom: compares the optimized decoder against an in-test oracle (the original implementation, verbatim) over all 1- and 2-byte inputs × every truncation length, a boundary sweep of 3-byte inputs, and 200k randomized longer/malformed inputs. Zero divergence in value, byte count, or throw/no-throw. Runs ~1s under Debug/ASan.
• Decoded-output FNV-1a fingerprint over the real bag is unchanged (0x75b0cc1fbc0457e9) — exposed via a new mcap_codec_benchmark --hash correctness gate.
• Full ctest green. Independently reviewed (adversarial differential sweep up to 67M cases under ASan, zero mismatches; bounds-safety verified — buf[1] is read only under a short-circuited max_size >= 2 guard, so no out-of-bounds read on truncated input).

Scope & notes

• The encoder (encodeVarint64) and the wire format are untouched — round-trip contract preserved.
• Explored and rejected during this work (no gain / regressions, all reverted): SIMD-izing the FloatN int→float convert (store-forwarding stall, −2%), devirtualizing per-point dispatch (V5 −4%), decoder caching (0% wall-clock — a profiler artifact), and a 3-byte fast path (−1.5%, the case is too rare here). The dominant remaining decode hotspot (FloatN, ~42%) is data-dependency-bound; further decode gains would need a SIMD-decodable varint wire format (e.g. Stream VByte) — a separate, larger change.
• Pre-existing, not introduced here (flagged by review for a possible follow-up): signed-shift UB in encodeVarint64's zigzag (value << 1 on negative), and the INT64_MIN ↔ NaN-marker collision. Neither arises from real quantized/delta point data.

Commits

1. perf(decode): fast-path 1/2-byte varints in decodeVarint (+ --hash benchmark tooling)
2. test(decode): differential oracle test for the fast paths
3. refactor(decode): address review — trim test sweep to 200k, reject --hash without --decode-replay

🤖 Generated with Claude Code