Skip to content

refactor(hll): simplify coupon serialization and documentation - #291

Merged
tisonkun merged 3 commits into
apache:mainfrom
tisonkun:codex/hll-compact-serialization
Oct 5, 2026
Merged

tisonkun merged 3 commits into
apache:mainfrom
tisonkun:codex/hll-compact-serialization

Conversation

@tisonkun

@tisonkun tisonkun commented Oct 5, 2026 •

Copy link
Copy Markdown
Member

HLL List and Set serialization always produces compact images, but both writers retained a hard-coded compact = true and unreachable output branches. Remove those branches and use the existing coupon iterators, preserving the declared List count, coupon order, and serialized bytes.

Focus HLL public documentation on caller-visible contracts, including hashing compatibility and union precision. Keep independently runnable examples on public methods so callers can use each entry point without reading the module overview. Remove internal mode descriptions and comments that restate the code, retain encoding and estimator invariants, correct stale preamble and table-range descriptions, and link non-obvious formulas and lookup tables to their upstream sources.

Validation:

  • cargo x check, cargo x test (753 tests, including 142 doctests), and cargo x lint passed, including rustdoc with warnings denied.
  • The documentation changes leave runtime code, numeric tables, and existing unit and integration tests unchanged.
  • Existing tests compare coupon-mode output byte-for-byte with 36 C++, Java, and Go reference images.
  • An external baseline/candidate probe matched serialized bytes and estimate bits for 175,887 states, covering all HLL types, lg_k 4–21, representation transitions, sparse updatable images, declared List count boundaries, and continued updates after deserialization.

@tisonkun tisonkun changed the title refactor(hll): make compact coupon serialization explicit refactor(hll): simplify coupon serialization and documentation Oct 5, 2026
@tisonkun
tisonkun merged commit 1d2d406 into apache:main Oct 5, 2026
10 checks passed
@tisonkun
tisonkun deleted the codex/hll-compact-serialization branch October 5, 2026 06:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant