DoubleRangeFacetCounts does not count -0.0 in a range that starts at an inclusive 0.0, although the range's own drill-down matches it

DoubleRange defines membership with plain double comparisons: accept(value) is value >= min && value <= max (range/DoubleRange.java:84-87 on main 645d4fe14a20), so -0.0 is inside [0, 1], and both getQuery(...) drill-downs match through accept(). DoubleRangeFacetCounts instead converts each range's bounds and every value with NumericUtils.doubleToSortableLong (DoubleRangeFacetCounts.java:255-270, :182, :225, :231, :273-275) and counts in that long order, where -0.0 (-1) sorts below +0.0 (0). A document whose value is -0.0 is therefore matched by an inclusive-0.0 bucket's own drill-down but not counted (and +0.0 at an inclusive -0.0 upper bound likewise); the split "< 0" + ">= 0" counts it in neither bucket; and the range [+0.0, -0.0], which the constructor's plain minIn > maxIn check accepts, makes counting throw IllegalArgumentException ... matches nothing. Counts are only ever too low and no query result changes. The divergence came with the LUCENE-5371 speed-up (8e1879225a35, first release 4.7.0); 4.6.1 counted with accept(). Every executed release through 10.6.0 and main fails. A 2-file fix that widens an inclusive zero bound in the long conversion passes the repro and the facet module's checks.

1. Membership is a plain comparison. range/DoubleRange.java:84-87:

   /** True if this range accepts the provided value. */
   public boolean accept(double value) {
     return value >= min && value <= max;
   }

Both drill-down queries built by getQuery(...) match through it: values.advanceExact(...) && range.accept(values.doubleValue()) (:195-196) and, multi-valued, if (range.accept(values.nextValue())) return true; (:298-300).

1. Counting is in sortable-long order. DoubleRangeFacetCounts.getLongRanges() builds new LongRange(label, doubleToSortableLong(range.min), true, doubleToSortableLong(range.max), true) (DoubleRangeFacetCounts.java:255-270), and every counting path maps each value the same way (:182, :225, :231; the field path through mapDocValue, :273-275, of the raw bits that DoubleDocValuesField stores, -0.0 included). doubleToSortableLong follows Double#compareTo (NumericUtils.java:41-42): -0.0 is -1, 0.0 is 0.
2. Where they split. For [0, 1] the counter starts at 0, so -0.0 (-1) is outside; accept(-0.0) is true. Mirror: +0.0 (0) is outside a counter range that ends at -0.0 (-1). A Z3 model proved that without a signed zero the count and accept() never disagree on the two single-valued paths, and that on the value-source path these two are exactly the mismatches.
3. The split-at-zero hole. An exclusive max of 0.0 is stored as Math.nextAfter(0.0, -Inf) = -Double.MIN_VALUE (DoubleRange.java:71-74), which is sortable -2. So "< 0" ends at -2, ">= 0" starts at 0, and -0.0 (-1) is in neither.
4. The throw. The constructor checks minIn > maxIn on doubles (:76-78, and 0.0 > -0.0 is false), so it builds [+0.0, -0.0]; the converted LongRange(0, -1) fails its own check (LongRange.java:74-76) with range "..." matches nothing (Range.java:38-40) when counting starts (RangeFacetCounts.java:65-68). The counter is built lazily, only when there are hits to count, so with no hits nothing is thrown.

Three documents with a DoubleDocValuesField value of -0.0, 0.5 and 2.0; the three counting paths are the field, DoubleValuesSource and MultiDoubleValuesSource constructors. Each document also holds a DoublePoint of the same value, used only for the points comparison; the counts read the doc values.

A plain main() probe with the default codec and no test framework gives the same: -0.0 (from Math.ceil(-0.25)) in [0,1]: accept 2, drill-down 2, facet count 1, on main and 10.6.0. With one multi-valued document {-0.0, 5.0}, getQuery(MultiDoubleValuesSource) matches it, and the field and MultiDoubleValuesSource counts are 0.

• Who can hit it. Applications that count range facets over a double with DoubleRangeFacetCounts, through any of its constructors (field, DoubleValuesSource or MultiDoubleValuesSource; single- or multi-valued), with a bucket that starts at an inclusive 0.0. That bucket shape is common: the facet demo's distance buckets are new DoubleRange("< 1 km", 0.0, true, 1.0, false) and so on. The values must include an exact -0.0, which ordinary code produces (Math.ceil(-0.25), -1 * 0.0, Double.parseDouble("-0.0")). The mirror case is +0.0 at an inclusive -0.0 upper bound.
• What it takes. Public API; default codec, IndexWriterConfig and searcher; no opt-in setting; one document.
• Effect. Silent wrong results: the bucket's count is one too low for each such document (for a multi-valued document, when none of its other values is in the bucket), while drilling into the bucket shows the document. FacetResult.value is too low as well when no other requested bucket counts the document. Counts are never too high, and deleted or non-hit documents are never counted. The only loud symptom is the [+0.0, -0.0] range, which throws.
• How likely. Rare: most double fields never hold a negative zero, the randomized range-facet tests never generate one (values from random().nextDouble()), and no public report was found since 4.7.0 (2014). A code search of the default branches found no use of DoubleRangeFacetCounts in Solr, Elasticsearch or OpenSearch (not a full inventory), so the known reach is custom applications built on lucene-facet.

The test asserts the inconsistency inside the class: range.accept(-0.0) is true, so the count of the one document must be 1. The test body has one document and no threads or random calls (ByteBuffersDirectory). The seed still drives the test framework's per-run randomization (codec, similarity, locale, time zone, file encoding); the result was the same in every recorded run, and a plain main() probe with the default codec and no test framework fails the same way. The file carries the Apache license header; with the fix applied, :lucene:facet:check passes with it included unchanged (license, format, lint, forbidden APIs and the test), so it can go into a PR as is.

Left out on purpose: the drill-down count (it is accept() per document), the other two counting paths, the mirror case, the split at zero and the [+0.0, -0.0] throw; they are in the explanation above.

cp $REPRO/TestDoubleRangeSignedZero.java $LUCENE/lucene/facet/src/test/org/apache/lucene/facet/range/
cd $LUCENE && ./gradlew :lucene:facet:test --tests TestDoubleRangeSignedZero -Ptests.seed=DEADBEEF -Ptests.asserts=true
# also with -Ptests.asserts=false

TestDoubleRangeSignedZero > testNegativeZeroCountedInRangeStartingAtZero FAILED
    java.lang.AssertionError: facet count of [0, 1] for one document with value -0.0 expected:<1> but was:<0>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:A2F9029A4FF0C2A7]:0)
        ...
        at org.apache.lucene.facet.range.TestDoubleRangeSignedZero.testNegativeZeroCountedInRangeStartingAtZero(TestDoubleRangeSignedZero.java:50)
:lucene:facet:test (FAILURE): 1 test, 1  failure

# the same with -Ptests.asserts=false; the same on the 10.6.0 and 10.5.2 release jars (assertions on and off)
# with the fix: :lucene:facet:test (SUCCESS): 1 test (assertions on and off)

• Contract. min and max are "Minimum (inclusive)" and "Maximum (inclusive" (DoubleRange.java:45, :48); accept() is "True if this range accepts the provided value" (:84); each getQuery() will "Create a Query that matches documents in this range" (:324, :340). For -0.0 in [0, 1] the count of a range and its own drill-down disagree.
• The upstream oracle. testRandomDoublesSingleValued computes expected counts with plain >= / <= ("slow but hopefully correct", TestRangeFacetCounts.java:1161-1176) and asserts that the facet count (:1222) and the drill-down count (:1232-1242) both equal it. Its values come from random().nextDouble() (:1090), so -0.0 never occurs.
• History. Up to 4.6.1 the count loop was if (rangeFR.ranges[j].accept(v)) { counts[j]++; } (4.6.1 RangeAccumulator.java:85-89). LUCENE-5371 (8e1879225a35, 2013-12-18) replaced that loop (if (ranges[j].accept(v)) on its branch) with the sortable-long counter; its CHANGES entry says only "Speed up Lucene range faceting from O(N) per hit to O(log(N)) per hit using segment trees" (lucene/CHANGES.txt:12748-12751), and the issue (#6435, body and 5 comments) never mentions zero or sign. Executed: 4.6.1 counts -0.0 in [0, 1], 4.7.0 does not; the commit's parent is consistent and the commit is not (both built from source).
• Not documented. No javadoc, package doc, CHANGES or MIGRATE text says that range facet counts treat the two zeros differently.

The strongest case for "intended": NumericUtils and DoublePoint order doubles by Double.compareTo. NumericUtils defines its encoding by it, DoublePoint range queries are "consistent with Double#compareTo" (DoublePoint.java:213; LUCENE-7594 / #8645 made the points' nextUp / nextDown follow it), DoubleRange.equals uses Double.compare, and the upstream test's own DoublePoint.newRangeQuery(range.min, range.max) drill-down agrees with the counter; both getQuery() javadocs suggest PointRangeQuery as possibly faster for an indexed field; and the three classes are @lucene.experimental, which leaves maintainers room to choose. So the counter is right and accept() is the odd one out.

Why it fails as a defence of today's behaviour: the facet module's own membership API (accept(), both getQuery()s) is the plain comparison, and the facet demo drills into a counted bucket with range.getQuery; the divergence came from a performance rewrite whose release counted -0.0 one version earlier; the counts follow neither order (in the split at zero, plain order puts -0.0 in ">= 0", Double.compare order with DoublePoint.nextDown(0.0) puts it in "< 0", the counter in neither); and equals (Double.compare) and hashCode (Objects.hash) both tell the zeros apart, which is about object identity and says nothing about membership. What the defence does show is that maintainers may prefer to fix the other side. Verdict: not intended, a defect.

One option was built and run in a scratch worktree of 645d4fe14a20; the other two are not built. Which side to change is the maintainers' call; option A changes no query result.

The finder's fix. The package-private DoubleRange.toLongRange() already does the conversion but is not called on main; it gains two lines, and DoubleRangeFacetCounts.getLongRanges() replaces its own 7-line new LongRange(...) with longRanges[i] = range.toLongRange();.

  LongRange toLongRange() {
+    // accept() uses primitive comparisons (-0.0 == +0.0) but sortable longs order -0.0 < +0.0:
+    // widen a zero bound so that both zeros are inside, as they are for accept()
+    double lo = min == 0.0 ? -0.0 : min;
+    double hi = max == 0.0 ? 0.0 : max;
     return new LongRange(
         label,
-        NumericUtils.doubleToSortableLong(min),
+        NumericUtils.doubleToSortableLong(lo),
         true,
-        NumericUtils.doubleToSortableLong(max),
+        NumericUtils.doubleToSortableLong(hi),
         true);
   }

Trade-offs

• Restores the pre-4.7.0 counts; no query, filter or drill-down result changes; no per-document cost (the added work runs once per range, when counting starts; no benchmark was run).
• Visible count change for buckets with a zero bound (up by the number of zeros of the other sign), so a CHANGES entry is appropriate. [+0.0, -0.0] counts both zeros instead of throwing.
• Counts still differ from a DoublePoint range query on signed zero, by design of points.
• The sandbox DoubleRangeFacetCutter repeats the conversion (DoubleRangeFacetCutter.java:74-86, read only) and is not covered; toLongRange() is package-private, so it would need the same two lines or a public helper.

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle, JDK 25: stock + test fails with assertions on and off; + fix: the test passes with assertions on and off.
• + fix: TestRangeFacetCounts 22 tests pass. + fix and the test: :lucene:facet:check BUILD SUCCESSFUL (format, ecj lint, forbidden APIs, licenses; :lucene:facet:test 307 tests, 7 skipped, 0 failures); :lucene:facet:test with assertions off: 307 tests, 0 failures.
• Earlier, shadowed onto the main jars: the finder's, the independent reproduction's, the intended-behaviour check's and the tie-break's tests pass, and TestRangeFacetCounts + TestDynamicRangeUtil pass 36 of 36 and 108 of 108 (3 iterations). With the fix the split at zero counts the three-document example as 0 + 3.
• Not run: the full Lucene test suite, nightly tests, the sandbox module.

Make accept() (and so both getQuery()s) compare with Double.compare, reject [+0.0, -0.0] in the constructor, and step exclusive bounds with signed-zero-aware helpers (like DoublePoint.nextUp / nextDown) so the split at zero stays complete. Not built.

Trade-offs

Counts stay as they are and match points; but it changes which documents existing drill-downs match (-0.0 leaves [0, x] buckets) and touches the constructor, accept() and both query classes.

A javadoc note that range facet counts order -0.0 below +0.0 while accept() and getQuery() do not.

Trade-offs

Leaves the miscount, the split-at-zero hole and the [+0.0, -0.0] throw in place.

Method: SMT (Z3) bit-precise IEEE-754 modelling of the DoubleRange-to-counter pipeline, a hunt unit (facet taxonomy and ranges); tier semi-formal. Obligation O2c, "counter membership in sortable-long space equals DoubleRange.accept", was posed as an expected-SAT counterexample search and returned SAT with value -0.0 and an inclusive min of +0.0; the first logged run already contained the signed-zero refinements, so the hypothesis was formed while modelling and witnessed by the solver. O2h (UNSAT) proves that on the value-source path the mismatch happens exactly for a zero value at an inclusive bound that is the opposite-signed zero, O2e and O2f (UNSAT) that no other mismatch exists on the value-source and raw-bit field paths, and O2d (SAT) gives the [+0.0, -0.0] throw. A bounded-exhaustive public-API harness (11 special values, 34,040 range sequences, 411,854 checks over three counting paths) found only the predicted classes: these two, the throw, and two exclusive-infinity classes that belong to LFV-313. The finder then wrote a public-API JUnit on the stock main jars; the independent reproduction added the multi-valued paths and the intended-behaviour check the split at zero. This doc's test is a one-method form of the finder's.