[GordonYuanyc]

Implements docs/sketch_analytics.md (#253): every sketch and framework reports its theoretical memory, update/query/merge ops, error bound per statistic, and the parameters that meet a target (ε, δ), for ASAPPlanner to call. ASAPPlanner pins asap_sketchlib by rev, so it moves to this API in its own PR.

One commit per step; review commit by commit.

Commits

Commit	What
fix(fold)!	CountMinSketchFold::new / CountSketchFold::new panic for full_cols > 65536 (MAX_FULL_COLS): a full column is a u16.
fix(bloom)!	Bloom::dimensions_for returns Option, widens until the exact rate (1 − (1 − 1/c)^n)^r meets the target, and returns None past BLOOM_MAX_BITS; with_capacity panics there. predicted_fpp uses the exact rate.
fix(capability)!	CountMinSketch Total is AsIfBuiltOverUnion, not Exact: under Nitro sampling it is an estimate.
docs(univmon)	UnivMon's distinct bound is 1.35/(kε²), the variance the proof derives; the tests check it.
feat! rename	estimated_memory_bytes → theoretical_memory_bytes everywhere.
feat(analytics) trait	SketchAnalytics, ErrorBound, ErrorMetric, NormScale, StatisticKind::QuantileInterpolated, shared helpers (P_med, est(d), h(k), lg).
feat(analytics) op-count	op-count feature: analytics::ops::count(f) returns the ops f performed. Off by default and free when off.
feat(analytics) × 7	One per doc family: counter matrices, heavy hitters, counter matrices with top-k, cardinality and membership, quantiles and sampling, UnivMon family, frameworks. Each adds the trait impls, the op instrumentation, and its tests in tests/analytics/.
style(analytics)	clippy and rustdoc.
docs(tests)	docs/tests.md rows for the new tests.
fix(analytics) × 4	Fixes from an independent review, below.

Decisions

• CountSketch sizing. ItemFrequency takes a chosen δ: ε = √(q/β) with β the largest per-row rate where P_med(d, β) ≤ δ. params_for picks the odd d ≤ 19 and width with the fewest counters, which gives d = 5, w ≈ 9.5/ε² at δ = 0.01 (ASAPPlanner's per-row 1/3 gave d = 47, past ASAPv1's 20 rows). Contract count_sketch_l2_median_chosen_row_rate_v1; the heap, Space-Saving, fold, L2-norm and UnivMonQ variants follow it.
• Kll Rank. rank() returns a count, so Rank is Absolute(L1) with a fit measured on asap_sketchlib: ε = 2.07·s(δ)/k^0.9646 at 99%, contract kll_rank_measured_99_v1. Measured: 99th percentile of |rank(x) − true rank|/n over 1000 seeded trials × 9 query points, n = 10^6, m = 8, k from 32 to 4096; the regression is 1.8647/k^0.9646, and 2.07 makes it an upper envelope of every measured k.
• Statistics. The trait covers StatisticKind only. Doc rows for Min, Max and Sum (DDSketch, UnivMonQ) and for Totals without an accessor (CocoSketch, SpaceSaving, UniformSampling) are dropped, matching the capability table.

Formulas corrected by counting

The op tests count every access under op-count and check it against the formula; the doc now states what the code does. The larger corrections:

• h(k) (a TopKHeap update): 8 + 16·⌊log2 k⌋ → 8 + 14·⌊log2 k⌋.
• SpaceSaving: update ≤ 47, merge 44m + 2m·lg(2m) + 13.
• Kmv: update k + 3 + 6·⌊log2 k⌋. Bloom: update r on both paths (no inserted count).
• Kll: update average 15 + lg(c_b + 1), merge B·lg B + 16R + 8L + 40; queries count L(n) + 1 levels.
• Fold same-level merge, UnivMon merge and query, Hydra, ExponentialHistogram and TumblingWindow costs were undercounted and are restated.
• ElasticSketch's δ is e^−min(d, 5): light row 5 shares the heavy part's seed.

Other public API

• memory_bytes() on the sketches and frameworks that lacked it (CHANGELOG lists them); SpaceSaving, Bloom, UnivMonTwoTier and UnivMonQ gain an inherent theoretical_memory_bytes; SetAggregator::contains.
• Breaking: CountMinFastOps and CountSketchFastOps require memory_bytes.

Independent review fixes

Eight reviewers read the diff against the spec without the author's conclusions; the confirmed findings are fixed in the four fix(analytics) commits:

• theoretical_memory_bytes returns Option<usize>: None when it needs an input the section gives no bound for (key, label or mean key bytes), where an unknown key length used to count as 0.
• A merged: Option<bool> data input: SpaceSaving, ElasticSketch, the folds' TopK and Hydra's Kll readouts give a bound only for an unmerged state.
• Sizing that met a different bound than theoretical_error reports (HLL Classic), returned parameters new rejects (fold level for W < 8), or returned None too early (CountSketchWithL2Norm under the 128-bit hash, DdSketch for ε ≥ 1).
• Octo's τ_max/τ_min include the initial threshold; UnivMonQ's Quantile/Rank condition reads F̂₂·M < n² instead of a flag; DdSketch checks the indexable range; Kll Rank needs k ≥ 32; HLL uses Flajolet's constants below 128 registers; Hydra's and EH's HLL Distinct have no bound (a standard error mixed with a probabilistic term).
• Op models: std BinaryHeap::pop (7 + 5⌊log2 n⌋), TopKHeap::clear (2 per resident), SpaceSaving merges of unequal capacities.
• Op counting whose argument did work (cells()) is behind #[cfg(feature = "op-count")], so the default build does none of it.
• Tests that could not fail (UnivMonQ ItemFrequency, Hydra Count-Min) and weak ones (UnivMon Distinct, UnivMonQ quantiles on ordered data, FastPath non-power-of-two widths) are rebuilt and mutation-checked.

Tests

tests/analytics/ (156 tests with all features, 108 without op-count): memory against memory_bytes(), counted ops against each formula at two or more sizes, error bounds as binomial failure rates over independent trials, and sizing against its own bound. Every error test is mutation-checked: breaking the sketch's update or estimator (a dropped row, an ignored sign, a stale heap, a wrong compaction coin, …) turns it red.

Local: cargo fmt --check; cargo test --test asapv1_golden; clippy with -D warnings for default, --all-features, octo-runtime and experimental; cargo doc with -D warnings; cargo test --test analytics with default and all features; cargo test --doc; the lib tests of each sketch whose source changed. The pbt and e2e suites run in CI.

Not covered

• UnivMonQ readouts other than ItemFrequency have no op formula (they rebuild candidates through maps, sorts and isotonic regression).
• Octo is a runtime without one sketch type: its analytics are free functions (octo_error, octo_memory_bytes, octo_update_ops).
• Error tests cover the main readout of each family; Hydra's Kll/HLL/UnivMon cells, EH by mass and EHUnivMon's UnivMon tier have memory, ops and sizing tests only.

🤖 Generated with Claude Code