[zzylol]

Summary

Part of #239 — adds the posterior (query-time) sketch error estimator from
Chen, Wu, Yang, Jiang, Liu, "Precise Error Estimation for Sketch-based Flow
Measurement"
(IMC '21), as a pure, sketch-object-agnostic module, plus an opt-in
plan-time sizing option in boundary.rs motivated by the same paper.

What's implemented — the estimator (new asap_types::post_asap::error_estimation)

Fetched the paper (§3, §3.2, §3.3, and Appendix A.1 — including re-rendering
the PDF pages as images to verify formulas the text extractor garbled) and
implemented, as plain functions over &[u64]/&[i64] counter slices and
numeric params (no concrete sketch type involved — see "What's not
implemented" below for why):

• cms_posterior_error_bound — §3.1 Algorithm 1 (CM-Sketch): given
  one row's w counters, r rows, and target confidence 1-δ, returns the
  ⌊w·δ^(1/r)⌋-th largest counter as the error bound. (The paper's own
  Algorithm 1 pseudocode box prints ⌈wp⌉ while its prose says ⌊wp⌋ — an
  internal inconsistency in the source paper; this implementation follows
  the prose, documented in the function's doc comment. The two conventions
  differ by at most one rank, within the paper's own O(1/√w) bias bound.)
• cu_sketch_posterior_error_bound — Appendix A.1 Algorithm 2
  (CU-Sketch): the paper states this is identical to Algorithm 1 (both
  query paradigms return the min counter across rows), so this delegates to
  cms_posterior_error_bound rather than duplicating logic.
• count_sketch_posterior_error_bound — Appendix A.1 Algorithm 3
  (Count-Sketch): the median-based variant. Verified by rendering the PDF
  page as an image (the text extractor garbled the binomial-tail formula).
  Requires odd r — Theorem A.1 only states the optimal bound for
  r = 2k+1; the paper's footnote for even r ("similar equation for an
  even r") doesn't spell out the formula, so per the issue's instruction to
  "only implement what you can read and verify," even r returns None
  rather than guessing.
• classic_cms_sizing / traditional_a_priori_bound — the
  traditional a priori bound this issue is contrasted against (§3.3, just
  before Eq. 6): w = ⌈e/ε⌉, r = ⌈ln(1/δ)⌉, bound = ε·|F|₁. Necessarily
  a second implementation of the same formula as boundary.rs's private
  cms_width/cms_depth (asap-types sits below asap-aware-mapping in the
  workspace's dependency layering, so it can't import them) — pinned equal
  to boundary.rs's own worked example in a test so the two can't silently
  drift apart undetected.

Correctness evidence

The real, checkable property from the paper's Eq. 6 (posterior bound is
always ≤ the traditional worst-case bound for the same (w, r) sizing):
cms_posterior_bound_is_at_most_traditional_bound builds synthetic CMS rows
(uniform and skewed mass distributions, a fixed-seed deterministic PRNG —
no new crate dependency) across several (ε, δ) targets sized via
classic_cms_sizing, and asserts the posterior bound never exceeds
ε·|F|₁. A companion test nails the degenerate all-mass-in-one-counter
case, and kth_largest_pigeonhole_property checks the elementary fact the
paper's Eq. 6 proof leans on (k-th largest of w non-negative values
summing to T is ≤ T/k) directly and unconditionally.

Also: hand-computed examples, monotonicity (tighter bound as width grows
holding total mass fixed; rank grows monotonically with r), edge cases
(δ at 0/1 boundaries, all-zero counters, single row, empty row, even r
for Count-Sketch). 19 tests, all passing in
crates/types/src/post_asap/error_estimation.rs.

What I found re: sketch-runtime state (confirms the issue's premise)

Confirmed — this repo has no vendored CMS/CountSketch/CU-Sketch
implementation and no runtime counter-array data structure anywhere.
crates/types/src/post_asap/sketch.rs's SketchKind/SketchParams are
purely planning-time sizing metadata (width/depth/precision/k numbers, never
an actual counter matrix), and
crates/asap-aware-mapping/src/boundary.rs's default_size_params/
cms_width/cms_depth only ever compute those sizing numbers. A
rg/grep sweep for struct.*Cms, impl.*Cms, and any counter-array type
across the workspace turns up nothing beyond that metadata.

So the estimator functions above take plain counter slices rather than a
concrete sketch type, specifically so a future real sketch runtime's readout
path can call them directly on its real counter arrays with zero changes
needed here — see the module's doc comment for this stated explicitly.

What's wired for real — plan-time sizing (boundary.rs::posterior_aware_size_params)

New, purely additive function alongside (never called from, never changing)
default_size_params: given a caller-supplied ExpectedCaseSizing { width_relaxation } (a fraction in (0,1) of the worst-case cms_width the
caller is betting is enough for a non-adversarial workload), it sizes a
smaller CMS-family sketch (Cms/CmsWithHeap/CountSketch/
CountSketchWithHeap) — depth is left at the worst-case formula (relaxing
depth trades away confidence exponentially, a materially different and
riskier axis, out of scope here). The doc comment spells out exactly what's
being traded: the (ε,δ) guarantee becomes conditional on the stated
assumption holding, not unconditional — this function cannot and does not
verify the assumption, since no data exists at plan time.

This is not a literal call into the posterior estimator (there's no real
counter data at plan time to feed it) — it's this crate's own plan-time
analogue of the same "expected-case workloads need less" intuition, clearly
documented as such rather than overclaiming a direct connection to the
paper's technique.

Tests: width_relaxation < 1.0 produces a strictly smaller width than
default_size_params; width_relaxation == 1.0 (or any out-of-range value:
0.0, negative, >1.0, NaN, ∞) reproduces default_size_params
exactly; depth is unaffected; every CMS-family SketchKind is covered;
every other SketchKind is byte-for-byte identical to default_size_params;
and a regression pin confirms default_size_params's own existing behavior
is unchanged.

What's deferred, and why

• Runtime readout-time wiring (issue Add posterior (query-time) error estimation for CMS/CountSketch, per Chen et al. IMC'21 #239's integration point 1): not
  attempted — there is no real sketch runtime to wire into (see above). The
  estimator functions are ready to be called the moment one lands; that
  wiring is explicit follow-up scope for Add posterior (query-time) error estimation for CMS/CountSketch, per Chen et al. IMC'21 #239.
• Depth relaxation in posterior_aware_size_params: explicitly out of
  scope for this PR (see that function's doc comment) — a different,
  exponential-confidence tradeoff from width's linear one.
• Nothing from Appendix A.1 was skipped due to fetch failure — both
  CU-Sketch and Count-Sketch algorithms were verified by rendering the PDF
  pages as images after the text extractor garbled the formulas. The only
  narrowing is Count-Sketch's even-r case, deferred because the paper
  itself doesn't spell out that formula (see count_sketch_posterior_error_bound's
  doc comment).

Process

• cargo build --workspace --all-targets — clean
• cargo test --workspace — all passing (19 new tests in
  error_estimation.rs, 6 new tests in boundary.rs, no existing test
  changed)
• cargo fmt --all -- --check — clean
• cargo clippy --workspace --all-targets --all-features -- -D warnings —
  clean

🤖 Generated with Claude Code

[zzylol]

Reorganized per feedback: error_estimation.rs moved into a new post_asap::query_time/ submodule with its own module doc, making the execution-time vs. planning-time boundary visible in the folder structure itself, not just prose. crates/asap-aware-mapping/src/boundary.rs::posterior_aware_size_params (the real planning-time code from this PR) stays where it is — inside the planning crate — and its docs now cross-reference #250, filed to track actually connecting the two (feeding observed query-time posterior error back into a future replan) instead of leaving ExpectedCaseSizing a bare caller guess forever.

No behavior change — public paths (asap_types::post_asap::cms_posterior_error_bound etc.) are preserved via re-exports. cargo build/test/fmt/clippy all pass clean (459 tests, 0 failed).

[zzylol]

A code-review pass I ran (mistakenly targeting this PR's content while I asked it to review a different PR) surfaced 6 real findings against this branch. Verified each and fixed the legitimate ones:

• classic_cms_sizing now genuinely matches boundary.rs's cms_width/cms_depth — formula and clamps — instead of only the in-range formula (it previously returned (0, 0) for degenerate inputs and diverged silently outside a narrow range, contradicting its own "identical" doc claim).
• posterior_aware_size_params's match is now exhaustive over SketchKind (like default_size_params's), so a future sketch kind fails to compile here instead of silently inheriting worst-case sizing.
• relaxed_width now calls the existing private saturating_ceil instead of reimplementing its clamp inline.
• count_sketch_posterior_error_bound's fractile search is now O(r log w) (binary search + precomputed binomial coefficients) instead of O(w·r²).
• kth_largest now uses select_nth_unstable_by (O(w) avg) instead of a full sort (O(w log w)).
• query_time's internal re-export of error_estimation's functions is now a glob, so adding a function only needs one edit (the curated post_asap::mod list), not two.

All algorithmic changes verified output-preserving via the existing pinned/property tests (only the one test pinning the old degenerate-input bug needed its expected values updated). cargo build/test/fmt/clippy all pass clean (460 tests, 0 failed).