suaveplan/openspec/archive/2026-05-05-enterprise-universe-family/proposal.md

Why

The existing @suaveplan/geo package only covers Earth-surface geometry and mixes abstract math with Earth-specific constants. Neither the existing @suaveplan/day-night nor @suaveplan/geo is enterprise-grade, extensible to other planets, or observatory-accurate. This change introduces a seven-package astronomical core that provides real astronomical calculations, generalised planet-surface geometry, and a pluggable provider architecture.

What Changes

• Restructure @suaveplan/geo — abstract math extracted into new @suaveplan/geo; Earth-specific logic migrates to new @suaveplan/geo-earth.
• Create @suaveplan/geo-planet — configurable PlanetConfig and PlanetSurface for any planet's ellipsoid, atmosphere, and satellites.
• Create @suaveplan/universe — observer-centric astronomical core: coordinate frames, provider interfaces (SolarProvider, StarProvider, TidalProvider, WeatherProvider), UniverseClient plugin registry, and BitSchema wire protocols for star/body data.
• Create @suaveplan/solar-system — SolarProvider implementation using astronomy.js for real bodies plus Keplerian propagator for game-defined planets.
• Create @suaveplan/stars — StarProvider with bundled BSC5 catalog (~9k stars, bitpacked), swappable catalog source architecture, and deferred interfaces for Hipparcos/Tycho-2/Gaia.
• Rewrite @suaveplan/tides — enterprise-grade tidal prediction preserving TICON/ADMIRALTY Earth providers, adding physics-based multi-satellite model for any planet, TidalProvider adapter for universe, and full OTel/AbortSignal/Zod coverage. BREAKING: @suaveplan/geo public API is preserved but internal implementation changes; consumers should verify no dependency on internal file paths.

Capabilities

New Capabilities

• geo: Abstract spherical and ellipsoidal geometry — pure math with no planet-specific constants.
• geo-planet: Configurable planet surface geometry from PlanetConfig — ellipsoid, atmosphere, satellites, and orbital elements.
• geo-earth: Earth pre-configuration of geo-planet — WGS84, Moon, ISA atmosphere, plus geocoding, geohash, and coordinate formatting.
• universe: Astronomical observer model — ObserverPosition, CoordinateFrame, provider interfaces, UniverseClient plugin registry, and BitSchema wire protocols.
• solar-system: Solar system computation — real body positions via astronomy.js, Keplerian propagator for custom planets, seasons, equinoxes, solstices, lunar phases, eclipses.
• stars: Star catalog provider — BSC5 bundled source, swappable catalog architecture, atmospheric extinction, and deferred SurrealDB/Hipparcos/Tycho-2/Gaia interfaces.
• tides: Tidal prediction — Earth harmonic providers (TICON, ADMIRALTY) and physics-based multi-satellite model for any planet.

Modified Capabilities

• None.

Impact

• New packages: 7 packages across universal/geo, universal/astronomy, and universal/primitives plugin directories.
• Dependency graph: geo → geo-planet → geo-earth → universe → (solar-system, stars, tides).
• Downstream consumers: Any package depending on @suaveplan/geo internals must update to @suaveplan/geo-planet abstractions.
• Follow-up change: enterprise-gaming-universe builds the gaming layer (gaming-universe, gaming-environment-lighting) on top of this astronomical core.
• Deferred integrations: @suaveplan/weather (locked interface in WeatherProvider but no implementation), SurrealDB star storage, Hipparcos/Tycho-2/Gaia catalog sources, and R3F/Three.js rendering integrations are explicitly out of scope.