Ephemeris engines and adapters — High-Level Design

Status: Implemented modules · Part of: Ephemeris · Updated: 2026-10-28

Three calculation engines stand behind the ephemeris layer: Swiss Ephemeris, NASA JPL Horizons and Astronomy Engine. Each has exactly one adapter that translates its native calls into the shared contract. One Binder boundary owns validation, routing, normalization and base semantics, so Vedic and Western services never choose an engine or combine two answers.

This page is the architecture view. Calculation internals remain in the Swiss, NASA and Astronomy Engine module guides.

1. Purpose

A chart is only reproducible if every number can name the engine that produced it. Supporting three engines is therefore not “pick whichever is available”:

• Swiss Ephemeris is the default provider and source of record. It computes locally, supports houses, native sidereal modes and solar events, and is the only engine the product treats as authoritative by default.
• NASA JPL Horizons is the independent reference. The drift validator compares against it, and a host may declare it as a coverage fallback when Swiss files cannot serve a tropical position request.
• Astronomy Engine is an optional local provider. It removes the native binding and data-file requirement from the calculation path for hosts that select it, without changing the contract seen by consumers.

One decision per complete request keeps “the same chart” stable across natal, transit and panchang views, and preserves a single provenance record.

2. Where they sit

The diagram is a component map, not a request sequence:

Boxes represent modules or hosting boundaries. Source presence does not assert deployment, a live NASA comparison or production accuracy.

3. The three engines

3.1 Swiss Ephemeris

The adapter starts a fresh child process for every operation so Swiss’s process-wide observer, sidereal and time settings cannot leak between simultaneous requests. It verifies the pinned .se1 files, refuses the Moshier analytical fallback, pins the DE441 tidal model and computes houses from UT1. Sidereal conversion happens once inside the native calculation and is declared as provider-applied. Rahu uses the selected mean or true node; Ketu is its exact antipode.

The adapter advertises only the installed file range, not the library’s theoretical range. Polar house failures reject as undefined geometry rather than returning native fallback cusps under the requested system name. Worker deadline, concurrency and queue limits are per adapter instance and shared by every caller that reuses it.

3.2 NASA JPL Horizons

The Horizons adapter owns the remote service’s awkwardness: a pinned query template, one call per body, a descriptive user agent, per-attempt timeouts, a whole-operation deadline, bounded concurrency, backoff for throttling and 5xx, and a circuit breaker. It verifies the response signature, markers, headers and rows before reading a number; a format change fails loudly instead of producing plausible zeros.

It returns tropical positions in the apparent ecliptic of date and declares DE441 plus any per-body source identifiers. It refuses sidereal requests, lunar nodes and houses before any network call, and refuses topocentric requests unless the host explicitly allows sending observer coordinates to JPL. One body’s failure aborts its siblings, so a partial position set is never returned.

3.3 Astronomy Engine

The Astronomy Engine adapter is pure JavaScript: no Swiss code, native binding, data files or network. The engine supplies planetary states, parallax and frame transformations; local algorithms supply the named ayanamsas, mean and osculating nodes, six house systems and Hindu solar events. It supports both zodiacs and the full canonical body list.

Its advertised window is deliberately narrower than the library’s theoretical range, and its results are not numerically identical to Swiss apparent places. It blocks the calling event loop while calculating, so a host that selects it accepts that scheduling trade-off. Registering the adapter does not make it primary; routing policy does.

4. One adapter contract

Every engine implements the EphemerisAdapter port from @astrology/astronomy-contracts:

The port is deliberately narrow. An adapter validates before provider I/O, preserves or rejects the whole request, and never:

• selects itself or another provider;
• retries a failed calculation through a different engine;
• normalizes values, changes the requested zodiac convention, or rounds results;
• derives signs, nakshatras, motion, aspects or chart meaning;
• persists results, caches answers or exposes HTTP statuses.

Those choices belong to the router, normalizer, Binder and host, which is why adding an engine does not change the Vedic or Western public API.

5. How a request moves

The Binder is the only execution owner. Its stages are:

1. Validate the canonical request and reject unsupported shapes before any provider work.
2. Resolve Terrestrial Time through the host-supplied resolver; the Binder does not convert civil time itself.
3. Route the complete request to one eligible provider and obtain a decision with a reason and cache key.
4. Invoke the normalizing wrapper for that provider exactly once.
5. Normalize and check context: origin, zodiac, ayanamsa, body order and event window must match the admitted request.
6. Check identity against the startup capability snapshot so a swapped engine, binding or file set cannot inherit another result’s evidence.
7. Add shared semantics for position requests — signs, nakshatras and padas, motion and aspects — and return the canonical facts with provenance.

Derived reads such as declinations, mean longitudes and disc diameters are computed by the Binder from one routed position read. They do not trigger a second provider call.

6. Routing and admission

Routing answers one question: which single provider can serve this whole request now?

• The primary defaults to swiss-ephemeris. The host may set another registered provider as primary, but registration alone does not change the default.
• Capability matching checks feature, zodiac, ayanamsa, event definition, every requested body, house system and inclusive TT coverage, in that order.
• A coverage fallback is considered only for a positions request in the tropical zodiac, only when the primary failed with UNSUPPORTED_BODY or OUT_OF_EPHEMERIS_RANGE, and only when an explicit rule names the provider and every requested body.
• Runtime admission then checks health, breaker state and quota. The cache key is computed from provider identity, engine/binding/file versions and the complete request; a cache hit still requires health and quota admission.
• The breaker is rechecked after the cache probe, because that probe may await external I/O.

Two invariants matter more than the stage list:

1. One provider per response. Bodies are never split across engines and answers are never merged.
2. A failure is not a fallback trigger. Outages, open breakers, quota exhaustion, houses and sidereal requests never authorize substitution. The request fails with a typed error instead.

7. Normalization, identity and evidence

Each adapter is wrapped in a NormalizingAdapter, so normalization cannot be skipped by choosing a different engine. The wrapper validates the request again, calls the adapter once, then:

• validates canonical units, finite geometry and angle ranges;
• wraps angular fields once under the configured numeric policy;
• rejects a declaration whose origin, zodiac or ayanamsa differs from the request;
• rejects a body count or order that differs from the request;
• rejects a solar event outside the requested window or an unexpected sunset field;
• returns normalization provenance separately from the provider declaration.

Provider accuracy stays separate from decimal places. precisionArcsec remains null unless an engine can actually declare one; rounding to eight decimals is not an accuracy claim.

8. Failure modes

Consumers translate these into their own transport or UI behavior. Adapters do not invent HTTP statuses, and provider error strings or filesystem paths do not escape.

9. Ownership boundaries

A host that constructs the default Binder probes both Swiss and Horizons at startup, even when only one tradition is enabled. Astronomy Engine is constructed only when requested. Capability snapshots are detached at creation; a provider or configuration change requires a new Binder.

10. Limits and verification

• No deployment claim. These are workspace modules inside one package, not separately hosted services.
• No accuracy claim. Coverage windows, benchmark latencies and sampled agreement do not establish per-request precision. The recorded Astronomy Engine comparison is a sample at named dates, not a certification.
• No silent degradation. A provider that cannot serve the request fails; the Binder does not substitute another engine or synthesize a missing event.
• No shared native state. Swiss isolation depends on one child process per operation; reusing a single native engine is a diagnostic control, not a supported production path.
• No birth-data leakage. Horizons topocentric calls are opt-in because they send observer coordinates to JPL; logs omit request geometry.

The recorded Astronomy Engine benchmark and the drift validator are the current comparison evidence. Neither replaces independent fixtures or published-almanac acceptance for a new calculation family.

11. Related designs and source

• Astro Binder boundary
• Provider router
• Swiss adapter guide and implementation evidence
• NASA adapter HLD and module design
• Astronomy Engine adapter and benchmark
• Canonical normalizer
• Drift validator
• Package structure and application integration
• Binder vocabulary

Source:

• Binder assembly
• Provider router, selection, capability checks and runtime gates
• Swiss adapter and native engine
• Horizons adapter
• Astronomy Engine adapter
• Normalizing adapter and canonical normalizer