refactor: align internal symbol visibility

CONTRIBUTING.md

@@ -80,6 +80,12 @@ cargo bench --package benchmarks --bench benchmarks -- cpc::serde
 - End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
 - Put contract sections and compatibility notes before examples. When applicable, order sections as `# Errors`, `# Panics`, and `# Examples`. Include only sections that describe an actual contract.
 
+## Visibility
+
+- Let module visibility define the boundary for implementation items. Inside a private module, use `pub` when an item must be available outside its defining module. Inside a `pub(crate)` module, use `pub` when the item should be available wherever that module is visible. Do not repeat an enclosing restriction when it adds no narrower boundary.
+- Keep items private when they are used only by their defining module and its descendants.
+- For items reachable through a public module or a re-exported public type, use the narrowest visibility that supports their internal callers. Reserve unrestricted `pub` for intentional public API.
+
 ## Changelog
 
 - Update `CHANGELOG.md` in the same pull request for significant user-visible changes. Compare the final behavior with the latest release tag rather than recording the sequence of commits that produced it.

datasketches/src/codec/assert.rs

@@ -20,11 +20,11 @@ use std::ops::RangeBounds;
 
 use crate::error::Error;
 
-pub(crate) fn insufficient_data(tag: &'static str) -> impl FnOnce(std::io::Error) -> Error {
+pub fn insufficient_data(tag: &'static str) -> impl FnOnce(std::io::Error) -> Error {
     move |_| Error::insufficient_data(tag)
 }
 
-pub(crate) fn ensure_serial_version_is(expected: u8, actual: u8) -> Result<(), Error> {
+pub fn ensure_serial_version_is(expected: u8, actual: u8) -> Result<(), Error> {
     if expected == actual {
         Ok(())
     } else {
@@ -34,15 +34,15 @@ pub(crate) fn ensure_serial_version_is(expected: u8, actual: u8) -> Result<(), E
     }
 }
 
-pub(crate) fn ensure_preamble_longs_in(expected: &[u8], actual: u8) -> Result<(), Error> {
+pub fn ensure_preamble_longs_in(expected: &[u8], actual: u8) -> Result<(), Error> {
     if expected.contains(&actual) {
         Ok(())
     } else {
         Err(Error::invalid_preamble_longs(expected, actual))
     }
 }
 
-pub(crate) fn ensure_preamble_longs_in_range(
+pub fn ensure_preamble_longs_in_range(
     expected: impl RangeBounds<u8>,
     actual: u8,
 ) -> Result<(), Error> {

datasketches/src/common/inv_pow2.rs

@@ -17,7 +17,7 @@
 
 /// Compute 1 / 2^exp using the same bit construction as DataSketches Java.
 #[inline]
-pub(crate) fn inv_pow2(exp: u8) -> f64 {
+pub fn inv_pow2(exp: u8) -> f64 {
     f64::from_bits((1023 - exp as u64) << 52)
 }
 

datasketches/src/countmin/serialization.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-pub(super) const PREAMBLE_LONGS_SHORT: u8 = 2;
-pub(super) const SERIAL_VERSION: u8 = 1;
-pub(super) const FLAGS_IS_EMPTY: u8 = 1 << 0;
-pub(super) const LONG_SIZE_BYTES: usize = 8;
+pub const PREAMBLE_LONGS_SHORT: u8 = 2;
+pub const SERIAL_VERSION: u8 = 1;
+pub const FLAGS_IS_EMPTY: u8 = 1 << 0;
+pub const LONG_SIZE_BYTES: usize = 8;

datasketches/src/cpc/compression.rs

@@ -24,7 +24,7 @@ use crate::cpc::compression_data::LENGTH_LIMITED_UNARY_DECODING_TABLE65;
 use crate::cpc::compression_data::LENGTH_LIMITED_UNARY_ENCODING_TABLE65;
 use crate::error::Error;
 
-pub(super) fn encode_pairs(pairs: &[u32], lg_k: u8, output: &mut SketchBytes) -> usize {
+pub fn encode_pairs(pairs: &[u32], lg_k: u8, output: &mut SketchBytes) -> usize {
     let num_pairs = pairs.len() as u32;
     let num_base_bits =
         golomb_choose_number_of_base_bits((1 << lg_k) + num_pairs, u64::from(num_pairs));
@@ -57,12 +57,7 @@ pub(super) fn encode_pairs(pairs: &[u32], lg_k: u8, output: &mut SketchBytes) ->
     bits.finish()
 }
 
-pub(super) fn encode_window(
-    window: &[u8],
-    lg_k: u8,
-    num_coupons: u32,
-    output: &mut SketchBytes,
-) -> usize {
+pub fn encode_window(window: &[u8], lg_k: u8, num_coupons: u32, output: &mut SketchBytes) -> usize {
     let pseudo_phase = determine_pseudo_phase(lg_k, num_coupons);
     let encoding_table = &ENCODING_TABLES_FOR_HIGH_ENTROPY_BYTE[pseudo_phase as usize];
     let mut bits = BitWriter::new(output);
@@ -130,7 +125,7 @@ impl<'a> BitWriter<'a> {
     }
 }
 
-pub(super) fn decode_pairs(data: &[u8], num_pairs: u32, lg_k: u8) -> Result<Vec<u32>, Error> {
+pub fn decode_pairs(data: &[u8], num_pairs: u32, lg_k: u8) -> Result<Vec<u32>, Error> {
     if num_pairs == 0 {
         return Ok(vec![]);
     }
@@ -187,7 +182,7 @@ pub(super) fn decode_pairs(data: &[u8], num_pairs: u32, lg_k: u8) -> Result<Vec<
     Ok(pairs)
 }
 
-pub(super) fn decode_window(data: &[u8], lg_k: u8, num_coupons: u32) -> Result<Vec<u8>, Error> {
+pub fn decode_window(data: &[u8], lg_k: u8, num_coupons: u32) -> Result<Vec<u8>, Error> {
     let mut window = vec![0; 1 << lg_k];
     let pseudo_phase = determine_pseudo_phase(lg_k, num_coupons);
     let decoding_table = &DECODING_TABLES_FOR_HIGH_ENTROPY_BYTE[pseudo_phase as usize];
@@ -274,7 +269,7 @@ impl<'a> BitReader<'a> {
     }
 }
 
-pub(super) fn determine_pseudo_phase(lg_k: u8, num_coupons: u32) -> u8 {
+pub fn determine_pseudo_phase(lg_k: u8, num_coupons: u32) -> u8 {
     let k = 1u64 << lg_k;
     let num_coupons = u64::from(num_coupons);
     // This mid-range logic produces pseudo-phases. They are used to select encoding tables.

datasketches/src/cpc/compression_data.rs

@@ -17,7 +17,7 @@
 
 /// Notice that there are only 65 symbols here, which is different from our usual 8->12 coding
 /// scheme which handles 256 symbols.
-pub(super) static LENGTH_LIMITED_UNARY_ENCODING_TABLE65: [u16; 65] = [
+pub static LENGTH_LIMITED_UNARY_ENCODING_TABLE65: [u16; 65] = [
     // Length-limited "unary" code with 65 symbols.
     // entropy:    2.0
     // avg_length: 2.0249023437500000000; max_length = 12; num_symbols = 65
@@ -92,7 +92,7 @@ pub(super) static LENGTH_LIMITED_UNARY_ENCODING_TABLE65: [u16; 65] = [
 ];
 
 /// Reverse mapping for the length-limited unary code with 65 symbols.
-pub(super) static LENGTH_LIMITED_UNARY_DECODING_TABLE65: [u16; 4096] = [
+pub static LENGTH_LIMITED_UNARY_DECODING_TABLE65: [u16; 4096] = [
     256, 513, 256, 770, 256, 513, 256, 1027, 256, 513, 256, 770, 256, 513, 256, 1284, 256, 513,
     256, 770, 256, 513, 256, 1027, 256, 513, 256, 770, 256, 513, 256, 1797, 256, 513, 256, 770,
     256, 513, 256, 1027, 256, 513, 256, 770, 256, 513, 256, 1284, 256, 513, 256, 770, 256, 513,
@@ -336,7 +336,7 @@ pub(super) static LENGTH_LIMITED_UNARY_DECODING_TABLE65: [u16; 4096] = [
 /// encoding for rows containing more than one surprising bit).
 ///
 /// These permutations were created by the ocaml program "generatePermutationsForSLIDING.ml".
-pub(super) static COLUMN_PERMUTATIONS_FOR_ENCODING: [[u8; 56]; 16] = [
+pub static COLUMN_PERMUTATIONS_FOR_ENCODING: [[u8; 56]; 16] = [
     // for phase = 1 / 32
     [
         0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
@@ -436,7 +436,7 @@ pub(super) static COLUMN_PERMUTATIONS_FOR_ENCODING: [[u8; 56]; 16] = [
 ];
 
 /// Reverse mapping for column permutations.
-pub(super) static COLUMN_PERMUTATIONS_FOR_DECODING: [[u8; 56]; 16] = [
+pub static COLUMN_PERMUTATIONS_FOR_DECODING: [[u8; 56]; 16] = [
     [
         0, 1, 2, 3, 55, 4, 5, 6, 7, 8, 9, 10, 11, 12, 54, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22,
         23, 24, 25, 26, 27, 28, 29, 30, 31, 53, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44,
@@ -532,7 +532,7 @@ pub(super) static COLUMN_PERMUTATIONS_FOR_DECODING: [[u8; 56]; 16] = [
 ///
 /// Only the encoding tables are defined by this file. The decoding tables (which are exact
 /// inverses) are created at library startup time.
-pub(super) static ENCODING_TABLES_FOR_HIGH_ENTROPY_BYTE: [[u16; 256]; 22] = [
+pub static ENCODING_TABLES_FOR_HIGH_ENTROPY_BYTE: [[u16; 256]; 22] = [
     // Sixteen Encoding Tables for the Steady State.
 
     // (table 0 of 22) (steady 0 of 16) (phase = 0.031250000 = 1.0 / 32.0)
@@ -6326,7 +6326,7 @@ pub(super) static ENCODING_TABLES_FOR_HIGH_ENTROPY_BYTE: [[u16; 256]; 22] = [
 ];
 
 /// Reverse mapping for high entropy byte encoding tables.
-pub(super) static DECODING_TABLES_FOR_HIGH_ENTROPY_BYTE: [[u16; 4096]; 22] = [
+pub static DECODING_TABLES_FOR_HIGH_ENTROPY_BYTE: [[u16; 4096]; 22] = [
     [
         519, 1035, 771, 1567, 519, 1293, 783, 2081, 519, 1281, 771, 1809, 519, 1303, 783, 2609,
         519, 1035, 771, 1575, 519, 1299, 783, 2304, 519, 1285, 771, 1859, 519, 1545, 783, 3186,

datasketches/src/cpc/estimator.rs

@@ -88,15 +88,15 @@ static HIP_HIGH_SIDE_DATA: [u16; 33] = [
     5880, 5914, 5953, // 14 1000297
 ];
 
-pub(super) fn estimate(merge_flag: bool, hip_est_accum: f64, lg_k: u8, num_coupons: u32) -> f64 {
+pub fn estimate(merge_flag: bool, hip_est_accum: f64, lg_k: u8, num_coupons: u32) -> f64 {
     if !merge_flag {
         hip_est_accum
     } else {
         icon_estimate(lg_k, num_coupons)
     }
 }
 
-pub(super) fn lower_bound(
+pub fn lower_bound(
     merge_flag: bool,
     hip_est_accum: f64,
     lg_k: u8,
@@ -110,7 +110,7 @@ pub(super) fn lower_bound(
     }
 }
 
-pub(super) fn upper_bound(
+pub fn upper_bound(
     merge_flag: bool,
     hip_est_accum: f64,
     lg_k: u8,

datasketches/src/cpc/kxp_byte_lookup.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-pub(super) static KXP_BYTE_TABLE: [f64; 256] = [
+pub static KXP_BYTE_TABLE: [f64; 256] = [
     0.99609375, 0.49609375, 0.74609375, 0.24609375, 0.87109375, 0.37109375, 0.62109375, 0.12109375,
     0.93359375, 0.43359375, 0.68359375, 0.18359375, 0.80859375, 0.30859375, 0.55859375, 0.05859375,
     0.96484375, 0.46484375, 0.71484375, 0.21484375, 0.83984375, 0.33984375, 0.58984375, 0.08984375,

datasketches/src/cpc/pair_table.rs

@@ -27,7 +27,7 @@ const DOWNSIZE_DENOMINATOR: u32 = 4;
 /// This table stores `(row, col)` pairs and uses linear probing for collision resolution. It is
 /// optimized for scenarios where the cardinality of entries is low.
 #[derive(Debug, Clone)]
-pub(super) struct PairTable {
+pub struct PairTable {
     /// log2 of number of slots
     lg_size: u8,
     num_valid_bits: u8,

datasketches/src/cpc/serialization.rs

@@ -15,13 +15,13 @@
 // specific language governing permissions and limitations
 // under the License.
 
-pub(super) const SERIAL_VERSION: u8 = 1;
-pub(super) const FLAG_COMPRESSED: u8 = 1;
-pub(super) const FLAG_HAS_HIP: u8 = 2;
-pub(super) const FLAG_HAS_TABLE: u8 = 3;
-pub(super) const FLAG_HAS_WINDOW: u8 = 4;
+pub const SERIAL_VERSION: u8 = 1;
+pub const FLAG_COMPRESSED: u8 = 1;
+pub const FLAG_HAS_HIP: u8 = 2;
+pub const FLAG_HAS_TABLE: u8 = 3;
+pub const FLAG_HAS_WINDOW: u8 = 4;
 
-pub(super) fn make_preamble_ints(
+pub fn make_preamble_ints(
     num_coupons: u32,
     has_hip: bool,
     has_table: bool,

datasketches/src/cpc/sketch.rs

@@ -249,7 +249,7 @@ impl CpcSketch {
             .expect("surprising value table must be initialized")
     }
 
-    pub(super) fn surprising_value_table_mut(&mut self) -> &mut PairTable {
+    fn surprising_value_table_mut(&mut self) -> &mut PairTable {
         self.surprising_value_table
             .as_mut()
             .expect("surprising value table must be initialized")

datasketches/src/frequencies/reverse_purge_item_hash_map.rs

@@ -32,7 +32,7 @@ const MAX_SAMPLE_SIZE: usize = 1024;
 
 /// Linear-probing hash map for (item, count) pairs with reverse purge support.
 #[derive(Debug, Clone)]
-pub(super) struct ReversePurgeItemHashMap<T> {
+pub struct ReversePurgeItemHashMap<T> {
     lg_length: u8,
     load_threshold: usize,
     keys: Vec<Option<T>>,

datasketches/src/hash/seed.rs

@@ -27,7 +27,7 @@ use crate::hash::MurmurHash3X64128;
 /// # Errors
 ///
 /// Returns an error of `error_kind` if the computed seed hash is zero.
-pub(crate) fn compute_seed_hash(seed: u64, error_kind: ErrorKind) -> Result<u16, Error> {
+pub fn compute_seed_hash(seed: u64, error_kind: ErrorKind) -> Result<u16, Error> {
     use std::hash::Hasher;
 
     let mut hasher = MurmurHash3X64128::with_seed(0);
@@ -44,7 +44,7 @@ pub(crate) fn compute_seed_hash(seed: u64, error_kind: ErrorKind) -> Result<u16,
 }
 
 /// Checks that an actual seed hash matches the expected seed hash.
-pub(crate) fn check_seed_hash(
+pub fn check_seed_hash(
     expected: u16,
     actual: u16,
     name: &'static str,

datasketches/src/hll/array4.rs

@@ -43,13 +43,13 @@ use crate::hll::serialization::encode_mode_byte;
 const AUX_TOKEN: u8 = 15;
 
 #[derive(Clone, Copy)]
-pub(super) enum AuxFormat {
+pub enum AuxFormat {
     Compact,
     Updatable { lg_arr: u8 },
 }
 
 impl AuxFormat {
-    pub(super) fn from_header(compact: bool, lg_arr: u8) -> Self {
+    pub fn from_header(compact: bool, lg_arr: u8) -> Self {
         if compact {
             Self::Compact
         } else {
@@ -106,7 +106,7 @@ impl Array4 {
     /// Returns the true register value:
     /// * If raw < 15: value = cur_min + raw
     /// * If raw == 15 (AUX_TOKEN): value is in aux_map
-    pub(super) fn get(&self, slot: u32) -> u8 {
+    pub fn get(&self, slot: u32) -> u8 {
         let raw = self.get_raw(slot);
 
         if raw < AUX_TOKEN {
@@ -121,12 +121,12 @@ impl Array4 {
     }
 
     /// Get the number of registers (K = 2^lg_config_k)
-    pub(super) fn num_registers(&self) -> usize {
+    pub fn num_registers(&self) -> usize {
         1 << self.lg_config_k
     }
 
     /// Returns the estimate state independently from register-derived cached values.
-    pub(super) fn estimate_state(&self) -> EstimateState {
+    pub fn estimate_state(&self) -> EstimateState {
         self.estimator.estimate_state()
     }
 
@@ -298,7 +298,7 @@ impl Array4 {
     }
 
     /// Restores estimate state after copying or transforming the same logical sketch.
-    pub(super) fn restore_estimate_state(&mut self, state: EstimateState) {
+    pub fn restore_estimate_state(&mut self, state: EstimateState) {
         self.estimator.restore_estimate_state(state);
     }
 

datasketches/src/hll/array6.rs

@@ -82,17 +82,17 @@ impl Array6 {
 
     /// Get the unpacked 6-bit value (0-63) at the given slot
     #[inline]
-    pub(super) fn get(&self, slot: u32) -> u8 {
+    pub fn get(&self, slot: u32) -> u8 {
         self.get_raw(slot)
     }
 
     /// Get the number of registers (K = 2^lg_config_k)
-    pub(super) fn num_registers(&self) -> usize {
+    pub fn num_registers(&self) -> usize {
         1 << self.lg_config_k
     }
 
     /// Returns the estimate state independently from register-derived cached values.
-    pub(super) fn estimate_state(&self) -> EstimateState {
+    pub fn estimate_state(&self) -> EstimateState {
         self.estimator.estimate_state()
     }
 
@@ -164,7 +164,7 @@ impl Array6 {
     }
 
     /// Restores estimate state after copying or transforming the same logical sketch.
-    pub(super) fn restore_estimate_state(&mut self, state: EstimateState) {
+    pub fn restore_estimate_state(&mut self, state: EstimateState) {
         self.estimator.restore_estimate_state(state);
     }