Core: Add spherical geography bounds builder

[huan233usc]

Summary

Geography bounds metrics need an XY box that covers geodesic edges on a sphere, where an edge can bulge in latitude beyond its endpoints and where longitude is periodic. This adds a package-private SphericalGeographyBoundsBuilder in core that accumulates the bounds of geography points and minor great-circle edges through addPoint / addEdge / build, modeling each geography as a sphere.

• Compute the interior latitude extremum of each minor edge and conservatively expand it, so floating-point error cannot produce an under-covering latitude bound
• Merge the covered longitude intervals by removing the largest uncovered circular gap, producing an antimeridian-wrapping interval (west > east) when that is the tighter box
• Treat a vertex at a pole as having no longitude: it contributes latitude only, and a geography made up solely of pole vertices leaves longitude unconstrained and reports the full range
• Keep a coordinate on the antimeridian as given, so +180 and -180 are preserved rather than folded onto one sign and the same coordinate yields the same interval whether it arrives as a point or a degenerate edge
• Use world bounds for an ambiguous antipodal edge, and return no bounds for empty input or once an out-of-range coordinate is observed

The builder exposes only the spherical addPoint / addEdge / build kernel. Pole handling and the spherical interior-latitude extrema are kept separate internally so a follow-up can compose this kernel behind geography WKB traversal and algorithm dispatch, without introducing a single-implementation abstraction here.

Scope: geography, spherical only

This is the spherical algorithm kernel for a follow-up geography metrics integration. It deliberately does not add a generic GeographyBoundsBuilder, WKB traversal, Parquet writer wiring, polygon pole-containment detection, or spheroidal interpolation strategies such as Karney. Those belong in the integration layer, once another interpolation strategy exists, so this PR does not introduce a single-implementation abstraction prematurely.

Test Plan

• Cover interior latitude bulges north and south, endpoint-only latitudes, and 2,000 deterministic random edges sampled along their minor arcs
• Cover antimeridian wrapping, longitude interval union across disconnected lines, and largest-circular-gap selection
• Cover poles: pole-only geographies that use the full longitude range, poles mixed with finite vertices, both poles, and antipodal and coincident endpoints
• Cover invalid and empty input, where out-of-range, NaN, and infinite coordinates suppress the box
• Run the targeted core test class, formatting checks, and style checks

Verification Commands

./gradlew :iceberg-core:test --tests org.apache.iceberg.TestSphericalGeographyBoundsBuilder
./gradlew :iceberg-core:spotlessCheck
./gradlew :iceberg-core:checkstyleMain :iceberg-core:checkstyleTest

---

AI Disclosure

• Model: GPT-5
• Platform/Tool: Codex
• Human Oversight: partially reviewed
• Prompt Summary: Implement and refine a focused spherical geography bounding-box builder and correctness tests.

[szehon-ho]

The spherical kernel looks sound — I couldn't find a case where the latitude extrema or the longitude union under-cover an arc, and I traced the sweep by hand through the antimeridian, pole-only, and wrapping-interval cases. Two things seem worth resolving before merge: the pole convention, which can produce an X bound that excludes an X value present in the file, and the per-vertex interval accumulation, which makes writer memory scale with a file's vertex count.

Two questions: will the follow-up integration compute the query-side geography bounding box with this same builder? That decides whether the pole convention is an internal consistency choice or a cross-implementation hazard. And with no production caller yet, the pole and NaN conventions can't be validated end-to-end, which is exactly where a mismatch would surface.

[szehon-ho]

Add the pole vertex's stored longitude to longitudeIntervals rather than dropping it. The spec's geography X rule is numeric — an object matches if x >= xmin OR x <= xmax — and GeographyEvaluator.intersects compares the raw x values with no notion that the pole lies on every meridian. So addPoint(-120, 90) followed by addPoint(40, 10) gives x=[40, 40], a bound that excludes an X value present in the file, and a predicate whose literal bound keeps the pole's longitude (POINT(-120 90) → x=[-120, -120]) won't intersect it, so the file is pruned even though it holds a matching row. Including the longitude only widens the box, so it stays valid under the spherical reading too. addEdgeWithPole drops the pole endpoint's longitude the same way.

[szehon-ho]

Merge or compact these intervals as they accumulate instead of appending one per vertex. Nothing is ever removed, so a builder accumulating a whole data file holds one LongitudeInterval per vertex, and longitudeBounds() then allocates up to four LongitudeEvents per interval and sorts them — a file with 1M polygons at 100 vertices each is 100M edges. GeometryBoundsBuilder keeps O(1) state for the same job.

[szehon-ho]

Skip a NaN coordinate instead of latching INVALID for the whole file. POINT EMPTY is encoded as POINT(NaN NaN), so a single empty geography costs every other value in the file its bounds. The spec says NaN ordinates are skipped per dimension, and GeometryBoundsBuilder.DimensionBounds.add already does that. Suppressing on out-of-range coordinates still makes sense, since the sphere math has no meaning there.

[szehon-ho]

Document the contract here: build() returns null for empty input, one invalid coordinate turns bounds off permanently, an ambiguous antipodal edge yields world bounds, the box may wrap with west > east, and latitude extrema are deliberately widened so bounds are not tight. These are the details the follow-up integration has to reason about, and GeometryBoundsBuilder spells out the equivalent.

[szehon-ho]

Consider widening these ranges to reach the poles and near-180 longitude separations. Latitudes are drawn from ±70 and the separation from ±120, so no sampled arc passes near or over a pole — which is where "the minor arc spans the shorter endpoint longitude difference" is hardest to verify by inspection, since longitude sweeps almost 180° over a short arc there. Only (5, 10)-(175, 10) and (5, 10)-(-175.1, 10) cover that today.

[szehon-ho]

Assert that the bound is at least the true extremum rather than pinning the widened value. 70.20558550568438 is the exact vertex latitude times LATITUDE_SCALING_FACTOR, and the 1e-9 tolerance is far tighter than that 7e-6 offset, so tuning the margin means rewriting about ten expectations.