Initial Commit

openspec/archive/2026-05-05-enterprise-universe-family/specs/geo-earth/spec.md

@@ -0,0 +1,59 @@
+## ADDED Requirements
+
+### Requirement: Earth constant
+
+The system SHALL export a pre-built `EARTH` `PlanetConfig` using the WGS84 ellipsoid, Moon as a `SatelliteConfig`, and ISA atmosphere as `AtmosphereConfig`.
+
+#### Scenario: Earth constant validation
+
+- **WHEN** `EARTH` is imported
+- **THEN** `EARTH.name` equals `"Earth"`
+- **AND** `EARTH.radius` equals `6378137`
+- **AND** `EARTH.satellites` contains exactly one entry with `name` matching `"Moon"`
+
+### Requirement: Earth surface instance
+
+The system SHALL export a pre-built `earthSurface` `PlanetSurface` constructed from `EARTH`.
+
+#### Scenario: Earth surface delegation
+
+- **WHEN** `earthSurface.distance(a, b)` is called for two coordinates
+- **THEN** the result equals the WGS84 geodesic distance
+
+### Requirement: Geocoding provider interface
+
+The system SHALL export `GeocodingProvider`, `GeocodingResult`, `createInMemoryProvider`, and `batchGeocode`.
+
+#### Scenario: In-memory geocode
+
+- **WHEN** `createInMemoryProvider([{ name: "London", latitude: 51.5074, longitude: -0.1278 }])` is created
+- **AND** `batchGeocode` is called with `["London"]`
+- **THEN** the result contains one entry with matching coordinates
+
+### Requirement: Geohash encoding and decoding
+
+The system SHALL export `encodeGeohash` and `decodeGeohash` with round-trip fidelity.
+
+#### Scenario: Geohash round-trip
+
+- **WHEN** `encodeGeohash({ latitude: 51.5074, longitude: -0.1278 }, 9)` is called
+- **AND** the result is passed to `decodeGeohash`
+- **THEN** the decoded coordinate matches the original within `0.0001` degrees
+
+### Requirement: Coordinate parsing and formatting
+
+The system SHALL export `parseCoordinate` and `formatCoordinate` supporting DMS (degrees-minutes-seconds) and decimal formats.
+
+#### Scenario: Parse DMS string
+
+- **WHEN** `parseCoordinate("51°30'26.5\"N")` is called
+- **THEN** the result is approximately `51.5074`
+
+### Requirement: Preserve existing geo public API
+
+The system SHALL preserve all public exports that existed in the legacy `@suaveplan/geo` package.
+
+#### Scenario: Legacy export compatibility
+
+- **WHEN** all public exports of the legacy `@suaveplan/geo` are compared to `@suaveplan/geo-earth`
+- **THEN** every legacy export name exists in `geo-earth` with the same or broader type signature