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

## 1. geo — Abstract Geometry

- [ ] 1.1 Scaffold `@suaveplan/geo` package in `packages/geo/geo` with `package.json`, `tsconfig.json`, `vitest.config.ts` (100/100/100/100 thresholds)
- [ ] 1.2 Implement `Ellipsoid` type and `defineEllipsoid(a, b)` factory
- [ ] 1.3 Implement `SphericalCoord`, `Vec3`, `Mat3x3` types
- [ ] 1.4 Implement `geo/transforms` — `sphericalToCartesian`, `cartesianToSpherical`, `toRadians`, `toDegrees`
- [ ] 1.5 Implement `geo/distance` — `greatCircleDistance` and `vincentyDistance`
- [ ] 1.6 Implement `geo/bearing` — `bearing`, `destination`, `midpoint`
- [ ] 1.7 Implement `geo/angular` — `angularSeparation`
- [ ] 1.8 Implement `geo/bounds` — `BoundingBox`, `createBoundingBox`, `containsPoint`, `expandBox`, `mergeBoxes`, `intersects`
- [ ] 1.9 Implement `geo/polygon` — `pointInPolygon`, `polygonArea`, `polygonPerimeter`, `simplifyPolygon`
- [ ] 1.10 Implement `geo/units` — `DistanceUnit`, `convertDistance`
- [ ] 1.11 Add Zod schemas for all public option types
- [ ] 1.12 Add OTel spans on all public entrypoints
- [ ] 1.13 Write tests achieving 100% coverage for all source files
- [ ] 1.14 Write sibling `.md` docs for every implementation file
- [ ] 1.15 Write `README.md` with install, quick-start, and module links
- [ ] 1.16 Configure explicit named barrel exports for all subpaths (no `export *`)
- [ ] 1.17 Run `bunx turbo lint typecheck test build --filter=@suaveplan/geo` and fix all errors
- [ ] 1.18 Run `bunx turbo test:coverage --filter=@suaveplan/geo` and verify 100%

## 2. geo-planet — Configurable Planet Surface

- [ ] 2.1 Scaffold `@suaveplan/geo-planet` package in `packages/geo/geo-planet`
- [ ] 2.2 Implement `PlanetConfig`, `AtmosphereConfig`, `SatelliteConfig`, `OrbitalConfig`, `PlanetTextureManifest` types with Zod schemas
- [ ] 2.3 Implement `PlanetSurface` class delegating geometry to `@suaveplan/geo`
- [ ] 2.4 Implement `atmosphericDensity(altitudeMetres)` using scale-height model
- [ ] 2.5 Implement `airMass(altitudeDeg)` using Kasten–Young formula
- [ ] 2.6 Add OTel spans and `AbortSignal` support on async methods
- [ ] 2.7 Write tests achieving 100% coverage
- [ ] 2.8 Write sibling `.md` docs and `README.md`
- [ ] 2.9 Configure explicit named barrel exports
- [ ] 2.10 Run lint, typecheck, test, build, and coverage gates

## 3. geo-earth — Earth Configuration

- [ ] 3.1 Scaffold `@suaveplan/geo-earth` package in `packages/geo/geo-earth`
- [ ] 3.2 Define `EARTH` `PlanetConfig` constant (WGS84, Moon, ISA atmosphere)
- [ ] 3.3 Create `earthSurface` `PlanetSurface` instance from `EARTH`
- [ ] 3.4 Migrate and preserve legacy `@suaveplan/geo` public API: geocoding, geohash, coordinate parsing/formatting
- [ ] 3.5 Implement `GeocodingProvider`, `GeocodingResult`, `createInMemoryProvider`, `batchGeocode`
- [ ] 3.6 Implement `encodeGeohash`, `decodeGeohash` with round-trip fidelity
- [ ] 3.7 Implement `parseCoordinate`, `formatCoordinate` (DMS and decimal)
- [ ] 3.8 Write parity checklist comparing legacy `@suaveplan/geo` to `geo-earth`
- [ ] 3.9 Add Zod schemas, OTel spans, and `AbortSignal` where async
- [ ] 3.10 Write tests achieving 100% coverage
- [ ] 3.11 Write sibling `.md` docs and `README.md`
- [ ] 3.12 Configure explicit named barrel exports
- [ ] 3.13 Run lint, typecheck, test, build, and coverage gates
- [ ] 3.14 Run dependent sweep: `bunx turbo test --filter=...@suaveplan/geo-earth`

## 4. universe — Observer Model, Frames, Plugin Registry, Wire Protocol

- [ ] 4.1 Scaffold `@suaveplan/universe` package in `packages/geo/universe`
- [ ] 4.2 Implement `ObserverPosition` discriminated union type
- [ ] 4.3 Implement `CoordinateFrame` union and `convertFrame`, `toHeliocentric`, `toGalactic`
- [ ] 4.4 Implement `CelestialBody`, `CatalogStar`, `ObservedStar`, `StarQueryOptions`, `TideExtreme` types
- [ ] 4.5 Implement `SolarProvider`, `StarProvider`, `TidalProvider`, `WeatherState`, `WeatherProvider` interfaces
- [ ] 4.6 Implement `UniverseClient` with typed `register` methods and `getScene`
- [ ] 4.7 Implement `UniverseScene` shape
- [ ] 4.8 Define `StarPacket` BitSchema (~11 bytes/star) with `packStars` / `unpackStars`
- [ ] 4.9 Define `CelestialBodyPacket` BitSchema with `packBodies` / `unpackBodies`
- [ ] 4.10 Add Zod schemas for all public option types
- [ ] 4.11 Add OTel spans on all public entrypoints
- [ ] 4.12 Add `AbortSignal` on all async provider interface methods
- [ ] 4.13 Write tests achieving 100% coverage
- [ ] 4.14 Write sibling `.md` docs and `README.md`
- [ ] 4.15 Configure explicit named barrel exports
- [ ] 4.16 Run lint, typecheck, test, build, and coverage gates

## 5. solar-system — Solar System Provider

- [ ] 5.1 Scaffold `@suaveplan/solar-system` package in `packages/geo/solar-system`
- [ ] 5.2 Add `astronomy-engine` dependency via catalog ref
- [ ] 5.3 Implement `AstronomyEngine` interface and default astronomy.js wrapper
- [ ] 5.4 Implement `createSolarSystemProvider` with injectable engine
- [ ] 5.5 Implement real body position computation (Sun, Moon, Mercury–Neptune, Pluto, Ceres)
- [ ] 5.6 Implement Keplerian propagator for custom planets with `OrbitalConfig`
- [ ] 5.7 Implement `angularDiameterArcmin`, `apparentMagnitude`, `heliocentricPosition` fields
- [ ] 5.8 Implement `getSunrise`, `getSunset` in UTC
- [ ] 5.9 Implement `getSeason`, `getNextEquinox`, `getNextSolstice` (default Earth, configurable planet)
- [ ] 5.10 Implement `getLunarPhase`, `predictEclipse`, `getConstellation`
- [ ] 5.11 Apply atmospheric extinction for surface observers with `AtmosphereConfig`
- [ ] 5.12 Add Zod schemas, OTel spans, `AbortSignal`
- [ ] 5.13 Write tests achieving 100% coverage (inject deterministic engine for unit tests)
- [ ] 5.14 Write sibling `.md` docs and `README.md`
- [ ] 5.15 Configure explicit named barrel exports
- [ ] 5.16 Run lint, typecheck, test, build, and coverage gates

## 6. stars — Star Catalog Provider

- [ ] 6.1 Scaffold `@suaveplan/stars` package in `packages/geo/stars`
- [ ] 6.2 Implement `RawStar` type with optional proper motion and parallax
- [ ] 6.3 Implement `StarCatalogSource` interface
- [ ] 6.4 Bitpack BSC5 catalog at build time into compact binary (~100 KB)
- [ ] 6.5 Implement `createBsc5Source` returning offline `StarCatalogSource`
- [ ] 6.6 Implement `StarProviderImpl` with priority-ordered sources
- [ ] 6.7 Implement horizon frame computation from `ObserverPosition`
- [ ] 6.8 Implement `getVisibleStars` with hemisphere query, altitude filter, magnitude filter, brightness sort
- [ ] 6.9 Implement `queryCone` returning `CatalogStar[]` without observer fields
- [ ] 6.10 Implement atmospheric extinction via Pogson's formula and Kasten–Young air mass
- [ ] 6.11 Implement `getStar` by catalog ID
- [ ] 6.12 Define `SurrealAdapterLike`, `SurrealStarProviderOptions`, `createSurrealStarSource` (structural interface, no hard dep)
- [ ] 6.13 Define deferred factory types: `createHipparcosSource`, `createTycho2Source`, `createGaiaSource` with `fetchFn` and `cacheFn`
- [ ] 6.14 Add Zod schemas, OTel spans, `AbortSignal`
- [ ] 6.15 Write tests achieving 100% coverage
- [ ] 6.16 Write sibling `.md` docs and `README.md`
- [ ] 6.17 Configure explicit named barrel exports (ensure `stars/catalogs/bsc5` is optional)
- [ ] 6.18 Run lint, typecheck, test, build, and coverage gates

## 7. tides — Enterprise Rewrite

- [ ] 7.1 Scaffold `@suaveplan/tides` package in `packages/geo/tides`
- [ ] 7.2 Preserve TICON harmonic engine, station data, and provider logic
- [ ] 7.3 Preserve ADMIRALTY provider logic and station data
- [ ] 7.4 Implement `createTiconProvider` returning `TidalProvider`
- [ ] 7.5 Implement `createAdmiraltyProvider(options)` with injectable `fetchFn`, `clockFn`, optional `cacheFn`
- [ ] 7.6 Implement `createPhysicsBasedProvider` for any `PlanetConfig` with satellites
- [ ] 7.7 Implement `tidalHeight` with multi-satellite superposition
- [ ] 7.8 Implement `satelliteTidalContribution` for per-satellite visualisation
- [ ] 7.9 Implement `TidalProviderImpl` routing Earth by name to `earthProviders`, non-Earth to `physicsProvider`
- [ ] 7.10 Add Zod schemas for all public option types
- [ ] 7.11 Add `TidesError` extending `@suaveplan/error` with stable `TIDES.*` codes
- [ ] 7.12 Add `AbortSignal` on all async methods
- [ ] 7.13 Add OTel spans, counters, histograms on every provider call
- [ ] 7.14 Write property-based tests (fast-check) on harmonic prediction engine
- [ ] 7.15 Write tests achieving 100% coverage
- [ ] 7.16 Write sibling `.md` docs and `README.md`
- [ ] 7.17 Configure explicit named barrel exports
- [ ] 7.18 Run lint, typecheck, test, build, and coverage gates
- [ ] 7.19 Run dependent sweep: `bunx turbo test --filter=...@suaveplan/tides`

## 8. Cross-cutting and Archive

- [ ] 8.1 Update `STATUS.md`: mark `geo`, `geo-planet`, `geo-earth`, `universe`, `solar-system`, `stars`, `tides` as completed
- [ ] 8.2 Update `SUMMARY.md` with per-package paragraphs
- [ ] 8.3 Update `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`
- [ ] 8.4 Update `MISSING.yml` via `bun scripts/generate-missing.ts`
- [ ] 8.5 Run `bunx markdownlint-cli2 --fix` on all touched root docs
- [ ] 8.6 Run `bunx turbo lint typecheck test` across the full universe-family filter set
- [ ] 8.7 Verify zero banned patterns in all new package `src/` directories
- [ ] 8.8 Verify zero `export *` in feature barrels
- [ ] 8.9 Verify zero direct `vitest`/`bun:test` imports in non-exempt packages
- [ ] 8.10 Verify every `.ts` has a sibling `.md`
- [ ] 8.11 Verify every package has a `README.md`
- [ ] 8.12 Verify no bare version strings in any new `package.json`
- [ ] 8.13 Archive change: move `openspec/changes/enterprise-universe-family` to `openspec/archive/2026-04-25-enterprise-universe-family`