refactor: ZeroBucket explicit lazy state & value semantics

.github/workflows/custom_CI.yml

@@ -0,0 +1,46 @@
+name: Custom CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      # 1. Checkout source
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # 2. Set up JDK 21
+      - name: Set up JDK 21
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: gradle
+
+      # 3. Make gradlew executable
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      # 4. Build local distribution
+      - name: Build local distribution
+        run: ./gradlew localDistro --stacktrace --no-daemon
+
+      # 5. Run unit  tests
+      - name: Run server tests
+        run: ./gradlew :server:test --stacktrace --no-daemon
+
+      # 6. Upload all test reports
+      - name: Archive test reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports-java-21
+          path: |
+            **/build/test-results/**/*
+            **/build/reports/tests/**/*

BUILDING.md

@@ -4,7 +4,7 @@ Building Elasticsearch with Gradle
 Elasticsearch is built using the [Gradle](https://gradle.org/) open source build tools.
 
 This document provides a general guidelines for using and working on the Elasticsearch build logic.
-
+test
 ## Build logic organisation
 
 The Elasticsearch project contains 3 build-related projects that are included into the Elasticsearch build as a [composite build](https://docs.gradle.org/current/userguide/composite_builds.html).

JenkinsFile

@@ -0,0 +1,39 @@
+pipeline {
+    agent any
+
+    tools {
+        jdk 'jdk_21' 
+    }
+
+    options {
+        skipDefaultCheckout()
+    }
+
+    stages {
+        stage('Checkout repository') {
+            steps {
+                git branch: 'main',
+                    url: 'https://github.com/Jingjia01/elasticsearch.git'
+            }
+        }
+
+        stage('Build local distribution') {
+            steps {
+                bat 'gradlew.bat localDistro --stacktrace --no-daemon'
+            }
+        }
+
+        stage('Run server tests') {
+            steps {
+                bat 'gradlew.bat :server:test --stacktrace --no-daemon'
+            }
+        }
+    }
+
+    post {
+        always {
+            junit '**/build/test-results/**/*.xml'
+            archiveArtifacts artifacts: '**/build/reports/tests/**/*', allowEmptyArchive: true
+        }
+    }
+}

docs/refactor-zero-bucket-notes.md

@@ -0,0 +1,54 @@
+# Refactor Notes: ZeroBucket (Task 1)
+
+## Summary
+
+Converted implicit lazy loading (sentinel values Long.MAX_VALUE / Double.NaN) into explicit state flags (indexComputed, thresholdComputed). Added static factories (fromThreshold, fromIndexAndScale) while retaining the original public constructor (deprecated) and the original APIs (minimalEmpty, minimalWithCount, merge, collapseOverlappingBuckets\*, compareZeroThreshold). Added equals/hashCode/toString for value semantics and stronger testability.
+
+## Key Changes
+
+| Aspect            | Before                                  | After                                                                           |
+| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
+| Lazy tracking     | Sentinels (Long.MAX_VALUE / Double.NaN) | Booleans (indexComputed / thresholdComputed)                                    |
+| Constructors      | Public constructor only                 | + fromThreshold / fromIndexAndScale (constructor kept, deprecated)              |
+| API compatibility | merge, collapse\*, minimalWithCount     | Preserved (restored where removed)                                              |
+| Value semantics   | None                                    | equals, hashCode, toString                                                      |
+| Tests             | None for ZeroBucket                     | Added ZeroBucketTests (lazy, merge, minimal, invalid input, collapse, equality) |
+
+## Rationale
+
+Explicit flags improve readability and reduce mental overhead. Factories clarify intent (threshold-driven vs index-driven). Value semantics simplify reasoning in future merging logic and aid debugging (toString includes internal state).
+
+## Risks & Mitigation
+
+| Risk                                                             | Mitigation                                                                                              |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Off-by-one index computation regression                          | Preserved original +1 logic in index() lazy path                                                        |
+| Breaking callers using removed methods                           | Restored original methods (merge, minimalWithCount, collapseOverlappingBuckets\*, compareZeroThreshold) |
+| Hidden performance cost from forcing both computations in equals | Acceptable; equality rarely on hot path; keeps simplicity                                               |
+
+## Tests Added
+
+- testFromThresholdLazyIndex
+- testFromIndexLazyThreshold
+- testMinimalEmptySingleton
+- testMinimalWithCount
+- testMergeKeepsLargerThreshold
+- testInvalidNegativeThreshold
+- testEqualityAndHashStable
+- testCollapseNoOverlapReturnsSame
+- testToStringContainsKeyFields
+
+All passed with:
+`./gradlew :libs:exponential-histogram:test --tests "*ZeroBucketTests"`
+
+## Evidence Pointers
+
+- Commit(s): refactor(zerobucket)... (and fix if needed)
+- PR: refactor: ZeroBucket explicit lazy state & value semantics (Task 1)
+- Build screenshot: ZeroBucketTests BUILD SUCCESSFUL
+- Diff: removal of sentinel logic / introduction of flags & factories
+
+## Future Follow-up (Not in Task 1)
+
+- Remove deprecated constructor after downstream code migrates to factories.
+- Consider benchmarking overhead of toString in large diagnostics.

gradle.properties

@@ -22,3 +22,6 @@ org.gradle.java.installations.fromEnv=RUNTIME_JAVA_HOME
 
 # if configuration cache enabled then enable parallel support too
 org.gradle.configuration-cache.parallel=true
+
+org.gradle.java.installations.auto-download=true
+org.gradle.java.installations.paths=C:/jenkins/jdks

libs/exponential-histogram/src/main/java/org/elasticsearch/exponentialhistogram/DownscaleStats.java

@@ -29,11 +29,50 @@
 import static org.elasticsearch.exponentialhistogram.ExponentialHistogram.MAX_INDEX_BITS;
 import static org.elasticsearch.exponentialhistogram.ExponentialHistogram.MIN_INDEX;
 
+/**
+ * Interface for collecting downscale data by adding bucket pairs and resetting state.
+ */
+interface DownscaleDataCollector {
+    /**
+     * Resets the data structure to its initial state.
+     */
+    void reset();
+
+    /**
+     * Adds a pair of neighboring bucket indices to track for potential merging.
+     *
+     * @param previousBucketIndex the index of the previous bucket
+     * @param currentBucketIndex the index of the current bucket
+     */
+    void add(long previousBucketIndex, long currentBucketIndex);
+}
+
+/**
+ * Interface for querying downscale statistics and computing scale reductions.
+ */
+interface DownscaleQueryProvider {
+    /**
+     * Returns the number of buckets that will be merged after applying the given scale reduction.
+     *
+     * @param reduction the scale reduction factor
+     * @return the number of buckets that will be merged
+     */
+    int getCollapsedBucketCountAfterScaleReduction(int reduction);
+
+    /**
+     * Returns the required scale reduction to reduce the number of buckets by at least the given amount.
+     *
+     * @param desiredCollapsedBucketCount the target number of buckets to collapse
+     * @return the required scale reduction
+     */
+    int getRequiredScaleReductionToReduceBucketCountBy(int desiredCollapsedBucketCount);
+}
+
 /**
  * A data structure for efficiently computing the required scale reduction for a histogram to reach a target number of buckets.
  * This works by examining pairs of neighboring buckets and determining at which scale reduction they would merge into a single bucket.
  */
-class DownscaleStats {
+class DownscaleStats implements DownscaleDataCollector, DownscaleQueryProvider {
 
     static final long SIZE = RamUsageEstimator.shallowSizeOf(DownscaleStats.class) + RamEstimationUtil.estimateIntArray(MAX_INDEX_BITS);
 
@@ -44,7 +83,8 @@ class DownscaleStats {
     /**
      * Resets the data structure to its initial state.
      */
-    void reset() {
+    @Override
+    public void reset() {
         Arrays.fill(collapsedBucketCount, 0);
     }
 
@@ -54,7 +94,8 @@ void reset() {
      * @param previousBucketIndex the index of the previous bucket
      * @param currentBucketIndex the index of the current bucket
      */
-    void add(long previousBucketIndex, long currentBucketIndex) {
+    @Override
+    public void add(long previousBucketIndex, long currentBucketIndex) {
         assert currentBucketIndex > previousBucketIndex;
         assert previousBucketIndex >= MIN_INDEX && previousBucketIndex <= MAX_INDEX;
         assert currentBucketIndex <= MAX_INDEX;
@@ -84,7 +125,8 @@ void add(long previousBucketIndex, long currentBucketIndex) {
      * @param reduction the scale reduction factor
      * @return the number of buckets that will be merged
      */
-    int getCollapsedBucketCountAfterScaleReduction(int reduction) {
+    @Override
+    public int getCollapsedBucketCountAfterScaleReduction(int reduction) {
         assert reduction >= 0 && reduction <= MAX_INDEX_BITS;
         int totalCollapsed = 0;
         for (int i = 0; i < reduction; i++) {
@@ -99,7 +141,8 @@ int getCollapsedBucketCountAfterScaleReduction(int reduction) {
      * @param desiredCollapsedBucketCount the target number of buckets to collapse
      * @return the required scale reduction
      */
-    int getRequiredScaleReductionToReduceBucketCountBy(int desiredCollapsedBucketCount) {
+    @Override
+    public int getRequiredScaleReductionToReduceBucketCountBy(int desiredCollapsedBucketCount) {
         assert desiredCollapsedBucketCount >= 0;
         if (desiredCollapsedBucketCount == 0) {
             return 0;