feat(kll): add weighted update

[shanielh]

Adds KllSketch::update_with_weight(item, weight), equivalent to calling update(item) weight times. This mirrors update(item, weight) on the KLL sketches in datasketches-java. The name follows CountMinSketch::update_with_weight.

Behavior

• If weight is smaller than the free capacity, the item is inserted weight times as plain updates. No compaction can happen on this path.
• Otherwise, the update builds an exact sketch of the weighted item and merges it in. Since an item at level h counts as 2^h, the exact sketch holds one copy of the item at each level whose bit is set in weight. Bits above the top level fold into weight >> 60 copies at level 60, because level capacities are only defined up to MAX_NUM_LEVELS (61). This path costs one merge with a sketch of at most 75 items, however large the weight.
• A weight of zero is a no-op, the same as FrequentItemsSketch::update_with_count.
• If the stream weight would exceed u64::MAX, it panics without modifying the sketch, the same as update.
• merge's body moves into a private merge_unchecked, so the weighted path can skip checks it has already done without discarding a Result. merge is otherwise unchanged.
• Serialization is unchanged.

Tests

New module tests-integration/tests/kll_test/update.rs:

• zero weight
• equality with repeated updates in exact mode
• a single item with a 2^40 + 12345 weight
• u64::MAX - 1 weight, with a serialization round trip
• large weights merged into a full sketch
• 10,000 weighted items in estimation mode, ranks within the k=200 error bound, with a serialization round trip
• strings
• overflow leaves the sketch unchanged

cargo x test, cargo clippy --all-features --all-targets --workspace -- -D warnings and cargo +nightly fmt --all --check pass locally. I did not run taplo, typos or hawkeye locally, so CI will be their first run.

Companion PR for datasketches-cpp: apache/datasketches-cpp#542

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The randomized accuracy test can fail legitimately, and the complexity documentation overstates the implementation guarantee.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Avoid probabilistic flakiness from random KLL compaction · New
• Remove unconditional logarithmic-cost promise · New
• Correct complexity claim for direct weighted insertion · New

What changed in this PR

Adds efficient weighted updates to KLL sketches.

Changes:

• Adds update_with_weight and internal merge refactoring.
• Adds weighted-update integration tests and changelog documentation.

File	Description
datasketches/​src/​kll/​sketch.rs	Implements weighted updates.
tests-integration/​tests/​kll_test/​update.rs	Tests weighted-update behavior.
tests-integration/​tests/​kll_test/​main.rs	Registers the new tests.
CHANGELOG.md	Documents the API.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.