fix(java): round UInt64 values to the nearest float and double - #4196

Why?

UInt64 documents doubleValue() as the way to read a value that has left the signed long range, and that accessor was one ulp low for one residue class in every binade from 2^53 up: halving the unsigned value first put the odd low bit below the double grid, so it could only nudge the result down instead of breaking the tie. floatValue() was worse — it narrowed through doubleValue(), so a second rounding could land a value exactly on a float midpoint, and the tie then broke by mantissa parity instead of by which side of the midpoint the integer is on. Examples (unsigned inputs):

In [2^63, 2^64) the float midpoint band is 1,024–1,025 values wide per midpoint, so on the order of 2^33 values in the top binade alone are mis-reported. UInt8/UInt16/UInt32 widen exactly, so UInt64 is the only broken wrapper. Nothing inside the repository calls either accessor, which is why the existing suite cannot see it.

What does this PR do?

Round once, straight to the target format. Non-negative payloads already narrow correctly under JLS 5.1.3, so they become a plain cast. The top unsigned binade [2^63, 2^64) is handled on an integer grid — 2^11 for double, 2^40 for float — whose quotient fits the target mantissa exactly, so the remainder decides the rounding and the quotient's parity decides the tie; the result is the correctly-rounded value by construction, with no second rounding. floatValue() no longer delegates to doubleValue().

Evidence

Differential census against a decimal-parse oracle (Double.parseDouble / Float.parseFloat of the unsigned decimal string, which JLS requires to be correctly rounded), old formula vs new on identical populations:

• 524,288 consecutive values from every binade start → old doubleValue() 2,046 wrong, new 0
• 5,000,000 random unsigned values → old doubleValue() 6,157 wrong, new 0
• 2,389,824 samples across the double and float midpoint bands → old 352 double and 1,050,624 float wrong, new 0 and 0

UnsignedTest gains three tests: literal spot checks (both mis-rounded classes above, plus MAX_VALUE and 2^63, which stay correct), a double sweep comparing against parseDouble across 64 grid points per binade 2^53…2^63 (640 disagreements before the fix), and a float sweep (108 disagreements before). All sweep loops are JDK-8 safe, so the JDK 8/11/17/21/25/26 CI matrix is safe.

• Red on pristine 8e93633 + the new tests: Tests run: 95, Failures: 3 → green after the fix: Tests run: 95, Failures: 0
• Full fory-core module: 2349 tests / 1 failure (ExpressionTest.testLiteralSourceRoundTrip, pre-existing — reproduces on the base commit)
• spotless:check / checkstyle:check pass; ASF license headers preserved; no new files

User-facing change

UInt64.doubleValue() and floatValue() may return a value one ulp different for inputs at or above 2^53; they now return the nearest representable float/double in every case. Nothing in the repository depends on the old results; downstream code comparing exact doubles could.

AI Usage Disclosure

• substantial_ai_assistance: yes
• scope: code drafting (fix), tests, PR body drafting
• affected_files_or_subsystems: java/fory-core/src/main/java/org/apache/fory/type/unsigned/UInt64.java, java/fory-core/src/test/java/org/apache/fory/type/unsigned/UnsignedTest.java
• ai_review: line-by-line self-review completed (rounding cases checked against IEEE-754 round-to-nearest-even on the 2^11/2^40 grids; red→green confirmed). The §5 two-reviewer AI review loop with persisted artifacts has not been attached yet; it can be run and linked before maintainer review on request.
• ai_review_artifacts: none persisted yet (see previous line)
• human_verification: mvn -pl fory-core test -Dtest=UnsignedTest red (3 failures) → green (0); full module 2349 tests / 1 pre-existing failure; decimal-parse census 2,046/6,157/1,050,624 wrong → 0; spotless/checkstyle clean
• performance_verification: N/A — integer-grid widening replaces a multiply-add; no serialization hot-path or wire-format change
• provenance_license_confirmation: original work under Apache-2.0; no third-party code introduced; license headers preserved