Initial Commit

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

@@ -0,0 +1,115 @@
+## ADDED Requirements
+
+### Requirement: ObserverPosition types
+
+The system SHALL export a discriminated union `ObserverPosition` with three variants: `surface` (planet + coord), `atmospheric` (planet + coord + altitude), and `space` (Vec3 + frame).
+
+#### Scenario: Surface observer construction
+
+- **WHEN** an `ObserverPosition` of type `surface` is constructed with a valid `PlanetConfig` and `SphericalCoord`
+- **THEN** the object validates successfully
+- **AND** the `PlanetConfig` is accessible inline without lookup
+
+### Requirement: CoordinateFrame types and conversion
+
+The system SHALL export `CoordinateFrame` as a union of `heliocentric`, `galactic`, and `custom`, plus pure conversion functions `convertFrame`, `toHeliocentric`, and `toGalactic`.
+
+#### Scenario: Identity conversion
+
+- **WHEN** `convertFrame(vec, heliocentric, heliocentric)` is called
+- **THEN** the result equals the input vector
+
+### Requirement: CelestialBody shape
+
+The system SHALL export a `CelestialBody` interface with name, type, altitude, azimuth, apparent magnitude, angular diameter, distance in AU, and heliocentric position.
+
+#### Scenario: Body validation
+
+- **WHEN** a `CelestialBody` object is constructed with all required fields
+- **THEN** Zod validation succeeds
+
+### Requirement: CatalogStar and ObservedStar shapes
+
+The system SHALL export `CatalogStar` (catalog-space, no observer fields) and `ObservedStar` (extends `CatalogStar` with altitude, azimuth, and extincted magnitude).
+
+#### Scenario: Observed star construction
+
+- **WHEN** an `ObservedStar` is created from a `CatalogStar` with added `altitude`, `azimuth`, and `extinctedMagnitude`
+- **THEN** the object satisfies both the `CatalogStar` and `ObservedStar` contracts
+
+### Requirement: SolarProvider interface
+
+The system SHALL export a `SolarProvider` interface with `getBodies`, `getBody`, `getSunrise`, and `getSunset`, all accepting `ObserverPosition`, `Date`, and optional `AbortSignal`.
+
+#### Scenario: SolarProvider cancellation
+
+- **WHEN** `getBodies` is called with an `AbortSignal` that is aborted before resolution
+- **THEN** the promise rejects with an abort error
+
+### Requirement: StarProvider interface
+
+The system SHALL export a `StarProvider` interface with `getVisibleStars` (returns `ObservedStar[]`), `queryCone` (returns `CatalogStar[]`), and `getStar`.
+
+#### Scenario: StarProvider query
+
+- **WHEN** `getVisibleStars` is called with a surface observer and `StarQueryOptions`
+- **THEN** the returned array contains only `ObservedStar` entries with `altitude` and `azimuth` populated
+
+### Requirement: TidalProvider interface
+
+The system SHALL export a `TidalProvider` interface with `predictHeight` and `getExtremes`, accepting `PlanetConfig`, `SphericalCoord`, `Date`, and optional `AbortSignal`.
+
+#### Scenario: Tidal prediction cancellation
+
+- **WHEN** `predictHeight` is called with an aborted signal
+- **THEN** the promise rejects with an abort error
+
+### Requirement: WeatherState and WeatherProvider interface
+
+The system SHALL export `WeatherState` and `WeatherProvider` with a locked interface for future `@suaveplan/weather` integration.
+
+#### Scenario: WeatherProvider registration
+
+- **WHEN** a `WeatherProvider` is registered with `UniverseClient`
+- **THEN** `UniverseScene.weather` is populated after `getScene`
+
+### Requirement: UniverseClient plugin registry
+
+The system SHALL provide `UniverseClient` with typed `register` methods for `solar`, `stars`, `tides`, and `weather` domains, returning `this` for chaining.
+
+#### Scenario: Register all providers
+
+- **WHEN** providers are registered for all four domains
+- **AND** `getScene` is called with valid observer and time
+- **THEN** the returned `UniverseScene` contains `bodies`, `stars`, `tides`, and `weather`
+
+### Requirement: UniverseScene shape
+
+The system SHALL export `UniverseScene` with `bodies`, `stars`, optional `tides`, and optional `weather`.
+
+#### Scenario: Scene without optional providers
+
+- **WHEN** only `solar` and `stars` providers are registered
+- **AND** `getScene` is called
+- **THEN** the scene has `bodies` and `stars`, with `tides` and `weather` undefined
+
+### Requirement: StarPacket BitSchema
+
+The system SHALL export a `StarPacket` BitSchema quantising RA, Dec, magnitude, altitude, azimuth, and spectral class into ~11 bytes per star.
+
+#### Scenario: Pack and unpack stars
+
+- **WHEN** an array of `ObservedStar` objects is packed via `packStars`
+- **AND** the buffer is unpacked via `unpackStars` with the correct count
+- **THEN** the unpacked array has the same length
+- **AND** each field is within the quantisation error tolerance of the original
+
+### Requirement: CelestialBodyPacket BitSchema
+
+The system SHALL export a `CelestialBodyPacket` BitSchema quantising altitude, azimuth, angular diameter, apparent magnitude, and body type.
+
+#### Scenario: Pack and unpack bodies
+
+- **WHEN** an array of `CelestialBody` objects is packed via `packBodies`
+- **AND** the buffer is unpacked via `unpackBodies` with the correct count
+- **THEN** the unpacked array has the same length and matching fields within tolerance