feat(intchunk): cold INT best-of-N lossless value chunk codec

[zzylol]

Summary

Implements PR5 of the holistic-compression design (DESIGN.md §1.2-1.4 + §8): a standalone, lossless cold-tier raw-value chunk codec at asap-gorilla-go/intchunk/. This is a self-contained library + tests + benchmark only. It is not wired into the agent encoder or the merger — integration (agent encode + decode-on-read StoreAPI + shared-ts) is the follow-up PR6/PR7.

Codec

Per-series-per-block best-of-N, all three candidates lossless; the smallest wins:

tag	codec	for
0	GORILLA_XOR	lossless float64 via prometheus/tsdb/chunkenc XOR (Gorilla). Always valid; fallback for true high-precision floats.
1	INT_FOR_DELTA	float→int64 via decimal scale exp, frame-of-reference (subtract base), delta, fixed-width bit-pack. Gauges.
2	INT_FOR_DOD	same scale+FOR but delta-of-delta. Counters/monotonic + the timestamp column.

Decimal-exactness guard (tryScaleToInt64) — the load-bearing trap-avoider: an INT_* candidate is only produced when float→int64→float round-trips bit-exactly at the chosen scale. Decode divides by the decimal-exact 10^e (never a rounded reciprocal — using a reciprocal multiply wrongly rejected most fixed-decimal series and inflated the exponent). Otherwise only Gorilla is offered.

Overflow chunk-cut (§1.4/§3 drift→re-base): a residual exceeding the integer width ends the chunk and starts a fresh one with a new base; each chunk is self-contained / independently decodable.

Header (§1.2): codec_tag:u8, n_samples:uvarint, timestamps as t0 + delta-of-delta varints; INT tags add scale_exp:i8, base:zigzag-varint, first_residual.

API surface

func Encode(samples []Sample) (EncodeResult, error)   // best-of-N; Chunks may be >1 on overflow cut
func DecodeChunk(chunk []byte) ([]Sample, error)
func DecodeChunks(chunks [][]byte) ([]Sample, error)
func PeekTag(chunk []byte) (CodecTag, error)
type Sample struct { T int64; V float64 }
type EncodeResult struct { Tag CodecTag; Chunks [][]byte; Bytes int }

Files: codec.go (header/tags/varint/zigzag/bit-pack), scale.go (exactness guard), intchunk.go (INT codecs + ts column + overflow cut), gorilla.go (XOR wrapper), bestofn.go (driver), codec_test.go, bench_test.go. Only new dep used is chunkenc (already transitive via prometheus/prometheus); go.mod/go.sum unchanged.

Benchmark (block=1000, real Serf datasets — bits/sample)

series	gor b/s	int b/s	gor/int	best-of-N winner
City-temp (fixdec)	55.17	19.57	2.82×	INT_FOR_DELTA
Dew-point-temp	54.98	18.73	2.94×	INT_FOR_DELTA
Stocks-USA	43.92	16.11	2.73×	INT_FOR_DELTA
Wind-Speed	56.56	15.65	3.61×	INT_FOR_DELTA
Motor-temp (float32)	21.50	47.85	0.45×	GORILLA_XOR
Air-pressure (hi-prec)	15.55	19.46	0.80×	GORILLA_XOR

Class roll-up verdict: fixed-decimal gor/int ≈ 2.22× → INT wins; high-precision float → Gorilla wins (best-of-N correctly falls back). The simpler FOR+fixed-width pack lands ~2.2-3.6× vs the design's VM-adaptive ~4.8× target, which is the deliberately-simple §1.3 tradeoff. Micro-bench: encode ~194 ns/sample, decode ~52 ns/sample.

Test plan

• go test ./... green (whole asap-gorilla-go module)
• lossless round-trip: gauges, monotonic counters, high-precision floats, constants, negatives/zero, single/two-sample, irregular timestamps, randomized fuzz (200 iters)
• best-of-N picks the smallest valid candidate (asserted vs direct candidate sizes)
• exactness guard rejects 15+ sig-digit floats & NaN/Inf ⇒ Gorilla chosen, round-trip exact
• overflow chunk-cut produces ≥2 independently-decodable chunks that recombine to the original (DELTA + DOD paths)
• go vet / gofmt clean
• bits/sample benchmark: INTCHUNK_BENCH_DIR=/path/to/per-series-json go test ./intchunk/ -run TestBenchmarkBitsPerSample -v (data lives outside the repo; test self-skips when unset)

NOTE: no integration and no deploy — follow-up PR6/PR7.

🤖 Generated with Claude Code