feat(asap-gorilla): Phase 1 block format encoder + decoder + index file

[zzylol]

Summary

Phase 1 of the Gorilla-S3-cold-engine — a new sibling Rust crate asap-gorilla/ that mirrors the canonical GORILLA1 block format defined by the Go gorillaprocessor under opentelemetry-collector-contrib-patch/processor/gorillaprocessor/. Bytes written by either side are interchangeable.

• block.rs — on-wire layout (magic, version, series_count, per-series meta_json + first_ts + first_val_bits + ts/val bit streams)
• encoder.rs — bit-for-bit mirror of the Go bitWriter + gorillaTimestampEncoder (delta-of-delta) + gorillaValueEncoder (XOR with leading/significant-bit window)
• decoder.rs — streaming SampleIter so the backend GorillaQueryEngine can scan cold-store chunks without materializing every sample
• index.rs — per-hour index.json catalog with prune_by_time and prune_by_label_hash helpers
• 19 round-trip / byte-compat / index / integration tests + a smoke bench: encode 7.4M pts/s, decode 21M pts/s, ~7.1 bytes/sample on a 100k linear walk

The cross-language byte-parity test against a Go-produced fixture skips when tests/golden/single_series.gor is absent; tests/golden/regen.sh documents the recipe for producing it once the Go-side fixturegen helper lands.

Files

• asap-gorilla/Cargo.toml, Cargo.lock, README.md, .gitignore
• asap-gorilla/src/{lib,block,encoder,decoder,index,error}.rs
• asap-gorilla/tests/{round_trip,byte_compat,index_file,integration}.rs
• asap-gorilla/tests/golden/{regen.sh,.gitkeep}

No other paths touched. No workspace Cargo.toml exists at repo root yet (sibling crates asap-precompute-rs / controller are standalone), so this PR adds the new crate as a third standalone sibling rather than touching workspace members.

Test plan

• cargo build --release clean inside asap-gorilla/
• cargo test --release — 19 tests + 1 doc-test pass (round-trip 8, byte-compat 4, index 4, integration 3)
• cargo clippy --release --all-targets -- -D warnings clean
• cargo doc --no-deps clean
• Smoke bench prints encode/decode rates (encode 7.4M pts/s, decode 21M pts/s, ~7.1 B/sample)
• Cross-language byte-parity test against a real Telegraf-encoded fixture — skipped at PR time; activates once tests/golden/regen.sh produces single_series.gor. The Go-side internal/fixturegen helper does not yet exist; once added, the byte-identical re-encode test activates automatically.

Notes for reviewers

Two spec interpretations worth surfacing:

1. Telegraf vs gorillaprocessor as "spec source": the brief named telegraf-patch/plugins/outputs/gorilla_s3/gorilla_s3.go as the canonical spec, but that file is a passthrough S3 uploader — it does not encode Gorilla blocks. The actual block encoder lives in opentelemetry-collector-contrib-patch/processor/gorillaprocessor/{bitwriter,encoder,compress}.go. This PR mirrors that file set bit-for-bit. Worth tightening in the Phase 0 design doc.

2. JSON metadata key ordering: the Go side serializes the label set from map[string]string, whose iteration order is randomized — that makes the Go encoder's bytes non-deterministic for identical inputs. asap-gorilla deliberately strengthens the contract by serializing labels through BTreeMap so its output is byte-stable. Cross-language byte-parity therefore requires the Go fixturegen sort keys before marshaling (or for us to compare via the parsed SeriesMeta struct rather than raw bytes). README documents this.

🤖 Generated with Claude Code