feat(spatial): Haversine + PointToSegment geodesic wrappers (stream-consumer surface)

[estebanzimanyi]

Summary

Two utility classes in utils.spatial wrapping MEOS geog_distance for the per-event spatial-predicate call sites of stream-side consumers (MobilityFlink, MobilityKafka).

Class	Signature	MEOS surface
Haversine.distance	(lon1, lat1, lon2, lat2) -> double	geog_distance(POINT, POINT)
PointToSegment.distance	(pLon, pLat, s1Lon, s1Lat, s2Lon, s2Lat) -> double	geog_distance(POINT, LINESTRING)

Both wrappers accept primitive doubles (lon, lat) rather than higher-level geometry objects, so callers in tight per-event loops avoid wrapping their (lon, lat) fields into JTS Geometry / TGeomPoint before each call.

Why these two specifically

Per the stream-side parity analysis (MobilityFlink #3 + MobilityKafka #1, both at 27/27 BerlinMOD-Q cells), every spatial-predicate call site in their pipelines currently uses a pure-Java fallback:

• pure-Java haversine formula for point-to-point distance
• pure-Java planar equirectangular projection for point-to-segment distance

Both fallbacks drift semantically from the MEOS operators used elsewhere in the same pipeline (e.g., eintersects_tgeo_geo, edwithin_tgeo_geo, nad_tgeo_geo — all WGS84 spheroidal). These two wrappers let the streaming consumers mechanically swap each TODO(meos) site to a JMEOS call so the pipeline shares spatial semantics end-to-end.

The 8 raw FFI declarations the consumers need (edwithin_tgeo_geo, eintersects_tgeo_geo, edisjoint_tgeo_geo, nad_tgeo_tgeo, nad_tgeo_geo, nad_stbox_geo, nad_stbox_stbox, tdistance_tgeo_geo, tdistance_tgeo_tgeo) are already in JMEOS main's functions.java per the multi-module merge of #9.

Tests

10 JUnit tests, all against MEOS-on-PostgreSQL ground truth (WGS84 spheroidal, use_spheroid=true):

HaversineTest (5):

• zeroDistanceForIdenticalPoints — identical point pair → 0.0
• shortMeridianSegment — 0.05° latitude → ~5 562 m
• brusselsToParis — (4.35, 50.85) → (2.35, 48.86) → ~263 538 m
• symmetric — d(a, b) == d(b, a)
• nonNegative — SF → Tokyo great-circle, ~8 270 km, positive

PointToSegmentTest (5):

• zeroAtEndpoint — point on the segment endpoint → 0
• zeroAtInterior — point on segment midpoint → 0
• perpendicularDistance — off-axis ~3.5 km
• beyondEndpointFallsBackToEndpoint — beyond-endpoint reduces to Haversine to endpoint
• degenerateSegmentReducesToHaversine — s1 == s2 case

$ mvn -pl jmeos-core test -Dtest='HaversineTest,PointToSegmentTest'
Tests run: 10, Failures: 0, Errors: 0, Skipped: 0

Branch base

Branched off main (post the #9 multi-module merge); independent of the in-flight CONFL'd PRs (#8, #12, #15, #16, #17) — those carry the codegen + multi-module structural work and don't gate this additive wrapper layer.

Downstream consumers

After this lands, the follow-up commits in MobilityFlink #3 and MobilityKafka #1 mechanically replace each TODO(meos) site with:

• Haversine.distance(lon1, lat1, lon2, lat2) for point-to-point
• PointToSegment.distance(pLon, pLat, s1Lon, s1Lat, s2Lon, s2Lat) for point-to-segment