astrology design library
Ephemeris3 MIN READ04 / 31

Swiss Ephemeris adapter — workspace module

Reading guide: The current package architecture defines the binder boundary. Sections below describe reference designs unless an implementation note says otherwise. Standalone facade, cache and provenance services are dropped; their integration responsibilities belong to the consumer.

Status: Implemented module · Part of: Astro Binder

The reusable @astrology/swiss-ephemeris-adapter package implements the standalone @astrology/adapter-contract port. Consumers import it into their own applications. Neither package hosts a server. The implementation evidence covers the native mapping, installed coverage, time model, and tests.

Package responsibilities

Package Owns Runtime dependency
@astrology/adapter-contract Canonical requests/results, capabilities, typed failures, validation, immutable fluent queries None
@astrology/swiss-ephemeris-adapter Swiss constants, flags, file verification, native worker lifecycle and result admission Shared contract and pinned sweph
Future NASA adapter Horizons request/response mapping and native capability refusals Shared contract; not implemented

The contract package does not import either provider. Swiss and a future NASA adapter share the same error class and DTO definitions; callers do not receive copies of those definitions from a provider-specific export.

Architecture

Reusable ephemeris workspace modules Implemented architecture: consumer applications and the Swiss Ephemeris adapter import the standalone adapter-contract package. Applications call SwissAdapter directly through Promise methods, without a server. The Swiss package owns an internal isolated child process, the native engine, and verified ephemeris files. A future NASA adapter will implement the same port; NASA runtime integration is not implemented. Reusable ephemeris modules Shared contract + native Swiss implementation. Consumer applications own their UI, transport and lifecycle. Consumer application Imports workspace packages Calls the adapter directly @astrology/adapter-contract Port + DTOs + validation + fluent requests Shared errors and capability declarations No runtime dependencies or transport policy Swiss module SwissAdapter capabilities · positions · houses Deadline + capacity + shared typed errors Internal child process · per operation Swiss engine · sweph 2.10.3-8 Isolated observer, zodiac and time model Pinned DE441-derived files SHA-256 + installed coverage NASA adapter · planned Same shared port and errors Tropical positions; no native houses imports Promise calls imports shared contract fork + IPC verifies and reads planned dependency One complete result + declaration, or AdapterError. No listener, routes, HTTP mapping, cache or astrology rules. Import and construction perform no I/O. Package: @astrology/swiss-ephemeris-adapter Future package, not a NASA integration claim. Contract compatibility is checked separately. labelled dependency or call module / resource package / process boundary shared contract / native engine

The shared contract and Swiss package are implemented. The NASA module and the binder’s facade/router/normalizer remain planned. Solid arrows show dependencies or calls, as labelled. The Swiss child process is internal native isolation, not a separate server or service.

Public API

SwissAdapter implements three Promise-returning operations:

  • capabilities() probes the native engine/files and advertises supported features and zodiacs.
  • positions(request) returns ordered geometry plus its provider declaration.
  • houses(request) returns twelve cusps and eight named angles plus its declaration.

Importing or constructing an adapter performs no I/O. Each operation validates where applicable, starts an isolated child process, verifies the pinned files, computes, admits the native result, and reaps the process before settling. Default capacity is four concurrent operations per instance with a five-second budget including startup. There are no retries or Moshier fallback.

Calculation rules

  1. Check the installed file identities and coverage; never advertise the full theoretical library range.
  2. Convert UTC to TT/UT1 with a consistently pinned DE441 tidal acceleration.
  3. Apply sidereal mode in Swiss once, and record that the provider applied it.
  4. Preserve returned native flags and reject unexpected fallback or invalid geometry.
  5. Map Ketu to the selected lunar node’s antipode, rather than inventing a native body id.
  6. Refuse polar house failures instead of returning native fallback cusps under the requested name.
  7. Return typed errors without HTTP statuses, provider error strings, or filesystem paths.
  8. Leave routing, caching, astrology interpretation and application transport to their owners.

Installed coverage is approximately 1800–2400. The implementation has no cancellation-token API and no established per-request precision estimate; precisionArcsec is null. Missing/altered files, overload, and worker failures fail closed. Timeout kills the native process.