Skip to content

refactor: align seed and internal naming - #164

Merged
tisonkun merged 15 commits into
mainfrom
codex/naming-drift-audit
Jul 25, 2026
Merged

refactor: align seed and internal naming#164
tisonkun merged 15 commits into
mainfrom
codex/naming-drift-audit

Conversation

@tisonkun

@tisonkun tisonkun commented Jul 25, 2026

Copy link
Copy Markdown
Member

Summary

This PR applies the approved subset of the naming-drift audit. It establishes an explicit distinction between a full 64-bit seed and its derived 16-bit seed_hash, standardizes the set-operation constructor style, and corrects several misleading or non-idiomatic internal names.

Breaking constructor changes

Theta and Tuple set-operation constructors now follow the same convention as the other sketches:

  • ThetaIntersection::default() uses the default seed; ThetaIntersection::with_seed(seed) accepts a custom seed.
  • ThetaAnotB::default() uses the default seed; ThetaAnotB::with_seed(seed) accepts a custom seed.
  • TupleIntersection::new(policy) uses the default seed; TupleIntersection::with_seed(policy, seed) accepts a custom seed.
  • TupleAnotB::default() uses the default seed; TupleAnotB::with_seed(seed) accepts a custom seed.

The previous new(seed) and new_with_default_seed forms are removed and the migration is recorded in CHANGELOG.md.

Commit-by-commit rationale

  1. 7f15f37S1: define seed terminology. Documents that seed is the full 64-bit hashing value, seed_hash is only the derived 16-bit compatibility fingerprint, and hash_seed must not be used as a synonym.
  2. 643a358S2: rename the full RawHashTable seed. Changes the internal hash_seed field, parameters, and accessor to seed, removing the only third synonym while leaving Count-Min row hash_seeds intact.
  3. 0646322S3: standardize seed-hash errors. Converts the remaining CPC and A-not-B outliers to the common incompatible seed hash wording while retaining A/B input context.
  4. 1278d7bC1: standardize set-operation constructors. Introduces consistent default-seed and custom-seed entry points across Theta and Tuple intersection and A-not-B operators; updates examples, tests, and the changelog.
  5. d7db047P1: align CPC confidence parameter names. Uses num_std_dev on public CPC sketch and wrapper methods while retaining the mathematical kappa name inside estimator internals.
  6. d073774P3: align ThetaUnionBuilder parameter names. Renames local parameters to factor and probability, matching the equivalent Theta and Tuple builders without changing method names or behavior.
  7. 9611f37P4: clarify the raw A-not-B type. Renames the shared internal operator from RawAnotB to RawThetaAnotB, making its relationship to RawThetaUnion and RawThetaIntersection explicit.
  8. 2a01ef3I2: name the hash-table threshold accurately. Replaces get_capacity with capacity_threshold, since the value controls resize or rebuild rather than reporting allocated vector capacity.
  9. 01914e5I3: use the approved entry lookup name. Replaces get_entry with entry, following the selected Rust-style accessor name.
  10. d45955cI4: expose intersection state directly. Renames the internal is_valid field to has_result, matching the actual state-machine meaning and the existing public method.
  11. b0d38fbI5: use the plural byte-count name. Renames byte_used to bytes_used and corrects its documentation because the method returns a count.
  12. b8d7242I6: follow mutable-accessor convention. Renames mut_surprising_value_table to surprising_value_table_mut, matching standard Rust _mut suffix usage.
  13. 76a78b9I7: correct the raw-view documentation. Describes the view as shared by Theta-family union, intersection, and A-not-B operations rather than union alone.
  14. 1264c3aUse Default for zero-configuration operators. Replaces zero-argument new() methods with Default implementations on ThetaIntersection, ThetaAnotB, and TupleAnotB, matching the existing CPC, T-Digest, and builder conventions. TupleIntersection::new(policy) remains because its policy is required.

Validation

Explicitly deferred

This PR does not change the RawThetaSketchView::theta or iter API, does not remove cached seed_hash fields, does not rename Coupon::from_hash, and does not include any other items from the audit that were not explicitly approved.

@tisonkun
tisonkun marked this pull request as ready for review July 25, 2026 14:14
@tisonkun
tisonkun requested a review from ZENOTME July 25, 2026 14:14
@tisonkun

Copy link
Copy Markdown
Member Author

cc @ariesdevil in case you're working on theta/tuple sketches as well. This can be a code/logical conflict.

@tisonkun
tisonkun enabled auto-merge (squash) July 25, 2026 14:14
@tisonkun
tisonkun merged commit 63c51bd into main Jul 25, 2026
10 checks passed
@tisonkun
tisonkun deleted the codex/naming-drift-audit branch July 25, 2026 14:26
@ariesdevil

Copy link
Copy Markdown
Contributor

Thx for informing me:)

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.

3 participants