feat(vector3d, count-hll): fill in Vector3D + per-bucket-HLL CountHll sketch

[GordonYuanyc]

What

• Vector3D — fleshed out the stub to full Vector2D parity: a rows × cols grid where each (row, col) cell is a depth-length bucket. Adds init/from_fn/fill, element + bucket accessors, fast_insert, the fast_query_min/median/max[_with_key] + aggregate family over bucket slices, Nitro hooks, custom serde (recomputes col mask), Index/IndexMut.
• CountHll — a Count Sketch grid whose cells are per-bucket HyperLogLogs (Vector3D<u8>, depth = 2^precision). Answers grouped distinct-count queries: insert(key, distinct_value) records that a value was seen for a key; estimate(key) returns the estimated number of distinct values seen for that key (median across rows suppresses hash-collision noise). Plus register-max merge and msgpack serde.

API impact

Purely additive — Vector3D had no real callers; only a new module + re-export were added. No existing API changed.

Fixes (PR review)

1 — API redesign: insert(key, distinct_value) / estimate(key)

The original single-input insert(value) / estimate(value) API was meaningless: estimate(value) returned the cardinality of whichever hash bucket value landed in, a number determined only by stream size and column count — the query value conveyed no information. The Count Sketch median across rows didn't suppress noise from other keys; it just averaged independent estimates of the same thing.

The redesigned API routes by key (hash128 → column selection) and records distinct_value into the HLL registers (hash64 → register/rank). estimate(key) now answers "how many distinct values were seen for this key?" — the intended grouped distinct-count use case. estimate_total_cardinality() is removed: after the redesign a single distinct value can appear in multiple buckets (once per key it is paired with), so the per-row column-sum no longer partitions the stream.

Related sketches are now documented in the module header: sketches::hll for total-stream distinct counting, and sketch_framework::hydra (Hydra with HydraCounter::HLL) for the same per-key distinct-count query with heap-allocated HLL objects per cell vs. CountHll's contiguous Vector3D<u8> layout.

2 — Hash capacity guard

with_dimensions asserts rows × col_mask_bits ≤ 128 at construction. Violated configurations previously caused shift overflow (debug) or silent bit-truncation (release); they now panic with a clear message.

3 — All rows contribute to estimates

estimate previously used a [f64; 16] fixed buffer with rows.min(16), so inserts updated rows 17+ but queries silently ignored them. Now builds a Vec<f64> over all rows. compute_median_inline_f64 already has a sort-based fallback for lengths > 5.

4 — Serde recomputes derived fields + validates invariants

Custom Deserialize via CountHllSeed (matching the Vector3D pattern) reads only buckets and precision from the wire and recomputes p_mask, col_mask_bits, col_mask. Now also validates on deserialization:

• buckets.depth() == 2^precision — a mismatched depth would cause out-of-bounds register access in insert
• rows × col_mask_bits ≤ 128 — same constraint as the constructor

Checks

• cargo fmt --all -- --check clean
• New code is clippy-clean (workspace has pre-existing uninlined_format_args lint debt in unrelated files, unaffected by this PR)
• cargo test --all-features --locked: 479 lib + integration tests pass (14 CountHll-specific)

🤖 Generated with Claude Code