Skip to content

feat(geo): add geographic foundations - #4

Merged
404khai merged 1 commit into
mainfrom
feat/phase-3-geo
Sep 1, 2026
Merged

feat(geo): add geographic foundations#4
404khai merged 1 commit into
mainfrom
feat/phase-3-geo

Conversation

@404khai

@404khai 404khai commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Summary

Implements Phase 3 of the Roadrunner roadmap with validated geographic values and straight-line distance calculations in roadrunner-core.

  • adds validated WGS 84 Coordinate values
  • adds inclusive axis-aligned BoundingBox values
  • adds Meters, Seconds, and KilometersPerHour domain types
  • exposes Distance as Roadrunner's canonical meter-based distance type
  • implements haversine_distance(Coordinate, Coordinate) -> Meters
  • extends graph Node values with validated coordinates
  • updates Phase 2 graph fixtures and traversal benchmarks for the new node contract

Validation boundaries

Coordinates reject non-finite values, latitudes outside [-90, 90], and longitudes outside [-180, 180].

Physical units reject negative, NaN, and infinite values. Their Serde implementations deserialize through the same validated constructors instead of bypassing invariants.

Bounding boxes require a south-west corner that does not exceed the north-east corner on either axis. Antimeridian-crossing boxes are explicitly deferred and rejected by this initial axis-aligned representation. Bounding-box deserialization also revalidates these invariants.

Haversine implementation

The calculation uses the Haversine formula with the mean Earth radius and clamps the intermediate Haversine value to [0, 1] to contain floating-point drift before the inverse trigonometric step.

Tests cover:

  • zero distance for identical coordinates
  • an equatorial quarter circumference
  • the known London-to-Paris distance
  • distance symmetry

The function returns Meters directly and represents straight-line surface distance, not road-network travel distance.

Graph integration

Node::new now requires a validated Coordinate, and nodes expose that coordinate through a typed accessor. Existing topology tests and the generated graph benchmark use Coordinate::ORIGIN, keeping benchmark behavior focused on adjacency traversal.

No edge cost, travel-time calculation, or routing algorithm is introduced; those remain assigned to later phases.

Validation

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
  • cargo test --workspace --all-features --locked — 27 tests pass
  • cargo bench -p roadrunner-core --bench graph_traversal --no-run --locked
  • RUSTDOCFLAGS=-Dwarnings cargo doc --workspace --no-deps --locked
  • git diff --check main...HEAD

@404khai
404khai merged commit 640cd50 into main Sep 1, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant