[zzylol]

Why

A planner prices a top-k heap before it builds one, and today it has to guess the heap's bytes. ASAPPlanner charges 24 bytes per heap entry for Count-Min/Count Sketch with a heap and for UnivMon, while the library holds far more: a WeightedFrequency candidate is a 56-byte struct plus its identity tuple and its encoded key, and an HHHeap resident is a 48-byte HHItem, an 8-byte digest and a 40-byte index entry. Neither type says what it holds, so every caller re-derives (and drifts from) the layout.

While measuring this, a retained WeightedFrequency candidate turned out to hold its identity tuple in a four-slot Vec (from collect::<Result<Vec<_>, _>>(), whose size hint starts at 0): 72 spare bytes per candidate for a one-value identity.

What

• HHHeap::estimated_memory_bytes(k, key): bytes a heap of capacity k holds once full of keys shaped like key.
• WeightedFrequency::estimated_memory_bytes(width, depth, capacity, identity): bytes a state of that shape holds once it retains capacity candidates shaped like identity.
• A retained candidate's identity tuple is allocated at its exact length. Retained candidates, scores and encodings are unchanged.

Stacked on #227 (the WeightedFrequency stack: #160 → #225 → #226 → #227), since WeightedFrequency is not on main yet.

How

Both functions add up the parts from the types' own size_of and the containers' growth:

• HHHeap: the struct, the HHItem array and the u64 digest array (both reserve min(k, 1024) and double from there), the digest index (std HashMap buckets for that reservation, grown as a fresh fill grows them, with its control bytes), and each resident's owned key bytes (a string's or byte slice's length, 0 for a number).
• WeightedFrequency: the struct, width × depth 8-byte cells, the candidate heap's slots (it is rebuilt each update by pushing up to capacity + 1 candidates, so max(4, next power of two ≥ capacity + 1) slots), and per candidate its identity tuple (size_of::<FrequencyIdentity>() per value plus Utf8 bytes) and its key (bincode::serialized_size of the identity).

Left out, and said so in the docs: index tombstones from evictions can make the HHHeap index rehash into twice its buckets, and a WeightedFrequency update briefly holds the previous heap's slots too.

Key code interfaces added / modified

src/common/heap.rs

impl HHHeap {
    /// Bytes a heap built by `HHHeap::new(k)` holds once `k` distinct keys shaped like
    /// `key` are resident: struct, `HHItem` array, digest array, digest index and owned
    /// key bytes. A memory model calls it to price a top-k heap before building one.
    pub fn estimated_memory_bytes(k: usize, key: &DataInput) -> usize;   // new
}

src/sketches/weighted_frequency.rs

impl WeightedFrequency {
    /// Bytes a `width × depth` state holds once it retains `capacity` candidates whose
    /// identity tuples are shaped like `identity` (only variants and string lengths
    /// matter): struct, cells, candidate slots, identity tuples and encoded keys.
    /// A memory model calls it to price a top-k frequency state before building one.
    pub fn estimated_memory_bytes(
        width: usize,
        depth: usize,
        capacity: usize,
        identity: &[FrequencyIdentity],
    ) -> usize;   // new
}

Usage, end to end: a planner pricing a top-k state per group before it builds any (numbers from running these calls at the head commit).

use asap_sketchlib::{DataInput, FrequencyIdentity, HHHeap, WeightedFrequency};

// 1. The planner chose Count-Min with a heap for `topk(10, sum by (path) (rate(m[1m])))`:
//    width 64, depth 3, heap capacity 1,000, keyed by one Int64 identity per item.
//    `cms_heap_bytes` is the bytes one group's state holds; the planner multiplies it by
//    the groups it expects and charges that as peak memory.
let cms_heap_bytes = WeightedFrequency::estimated_memory_bytes(
    64, 3, 1000, &[FrequencyIdentity::Int64(0)],
);
// 80 (struct) + 1,536 (cells) + 1,024 slots × 56 + 1,000 × (24 identity + 20 key)
assert_eq!(cms_heap_bytes, 102_960);

// 2. A 16-byte string identity at width 2,048, depth 5, capacity 256:
//    each candidate also owns the string (16) and a 36-byte key.
assert_eq!(
    WeightedFrequency::estimated_memory_bytes(
        2048, 5, 256, &[FrequencyIdentity::Utf8("0123456789abcdef".into())],
    ),
    130_128,
);

// 3. One UnivMon layer's heavy-hitter heap of 256 entries: `layer_heap_bytes` is what the
//    planner adds per layer next to the layer's Count Sketch counters.
let layer_heap_bytes = HHHeap::estimated_memory_bytes(256, &DataInput::U64(0));
assert_eq!(layer_heap_bytes, 35_440); // 96 + 256 × 48 + 256 × 8 + 512-bucket index
// With 9-byte type-tagged keys, each resident also owns its 9 bytes.
assert_eq!(HHHeap::estimated_memory_bytes(256, &DataInput::Bytes(&[0; 9])), 37_744);

Before this PR

A caller had no way to ask what a heap holds, and guessed: ASAPPlanner priced 24 bytes per entry. A WeightedFrequency state of capacity 1,000 with Int64 identities held 174,960 bytes, 72 of them per candidate in unused identity slots.

After this PR

The same state holds 102,960 bytes, and estimated_memory_bytes returns exactly that before the state exists. ASAPPlanner's plan selection can read these functions instead of hardcoding a per-entry size once its pin includes this PR.

Verification

• tests/heap_memory_bytes.rs (new; failed to compile before the functions existed): checks both functions against size_of and against the bytes actually allocated, counted by a global allocator: HHHeap filled with k ∈ {1, 3, 7, 8, 100, 1024, 2000, 5000} u64 keys and 9-byte keys, and WeightedFrequency after 4 × capacity updates for capacity ∈ {1, 7, 64, 100, 1000} with Int64 and Utf8+Bool identities. Passes.
• cargo test --all-features --locked --lib -- weighted_frequency heap: 120 passed. Doc tests for weighted_frequency: pass.
• cargo fmt --all -- --check, cargo clippy --workspace --all-targets --all-features --locked -- -D warnings: clean.
• Limitation: the index size follows std HashMap's table layout on the build target (16-byte control groups with SSE2 on x86, 8 elsewhere); a std change to that layout would show up as a failure of this test.

[zzylol]

Closing: main now provides f64 Count-Min and Count Sketch with heaps (#232), ASAPv1 serialization as the only format (#241) and TupleKey group-by keys (#237), so WeightedFrequency's own kernel and ASAP-WFREQ-1 format are redundant. The remaining gaps (shape and weight checks, an atomic checked f64 update, a full clear, opt-in rescoring of retained candidates, and estimated_memory_bytes) move to new PRs on main's heap sketches. The old head is kept on backup/feat/heap-memory-bytes-20261020-161432.