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