@latimer-woods-tech/ephemeris

One geocentric ephemeris for the whole portfolio. SELF:PRIME's Energy Blueprint charts, mysticapi's metered /v1/sky endpoints, and Kairos' Council's card power all resolve to the same longitudes, verified against JPL Horizons.

Runtime-agnostic and dependency-free — pure math plus the platform Intl. Runs unchanged in a Cloudflare Worker, in Node, and in the browser.

Why this package exists

Before it, two independent implementations of the same physics shipped side by side and disagreed by up to 2.5° — whichever you asked, one was wrong. Both also carried a reference-frame bug that put Mercury nearly a degree off (a quarter of Energy Blueprint charts changed a gate), and both placed Chiron ~180° from where it actually is. This package is the corrected, single source, and its first commit is a JPL-pinned golden-vector suite so the ephemeris can never silently fork again.

Full diagnosis: docs/ and the golden fixtures in src/jpl-fixtures.json.

Usage

import {
  resolveLocalTime,
  toJulianDay,
  toJDE,
  allPositions,
} from '@latimer-woods-tech/ephemeris';

// 1. Local birth clock → UTC, with ambiguity surfaced (never silently guessed).
const { utc, ambiguity, alternative } = resolveLocalTime(
  { year: 1979, month: 8, day: 5, hour: 18, minute: 51 },
  'America/New_York',
);
if (ambiguity === 'ambiguous') {
  // The wall clock names two instants (a fall-back hour). `alternative` holds
  // the second one — ask the user which they meant. An hour is 0.55° of Moon.
}
if (ambiguity === 'nonexistent') {
  // Clocks sprang forward over this reading; it never happened.
}

// 2. UTC → Julian Ephemeris Day (TT). toJDE applies ΔT. This is not optional:
//    every position function is defined against TT, and a birth clock is UT.
const jde = toJDE(toJulianDay(utc));

// 3. Apparent geocentric ecliptic longitudes for every body.
const sky = allPositions(jde);
sky.sun.longitude;       // degrees [0, 360)
sky.moon.latitude;       // degrees
sky.mercury.retrograde;  // boolean

Accuracy

Worst-case longitude error against JPL Horizons across 14 epochs (1900–2049):

| body | error | body | error | |---|---|---|---| | Sun | 0.006° | Saturn | 0.16° | | Moon | 0.004° | Uranus | 0.03° | | Mercury | 0.01° | Neptune | 0.01° | | Venus | 0.003° | Pluto | 0.01° | | Mars | 0.01° | Chiron | 0.49° |

Every body is inside a Human Design line (0.9375°); the planets are inside a few percent of one. Chiron is a chaotic centaur — its ~0.5° residual is a 2-body-model floor, not a defect, and it is held to a looser golden tolerance. The lunar nodes use the classical mean-node series (~0.5°) and are treated as regression fixtures rather than independently verified truth.

Ancient dates (outside 1800–2050)

Since v1.1.0 the planets automatically switch to Standish's long-range elements (Table 2a/2b, valid 3000 BC – 3000 AD) outside the 1800–2050 window, so BCE charts are ephemeris-grade too. Verified against JPL Horizons DE441 at −630 and −43 (positions.bce.test.ts): Sun/Mercury/Venus/Mars within 0.06°, every outer planet within ~0.4° (previously up to 8.5° — Saturn at −630). The Moon's BCE bound (0.25°) mostly absorbs ΔT-model disagreement with JPL, which is inherent to any BCE comparison. Within 1800–2050 results are bit-identical to v1.0.0.

What it does not do

• No houses, no Ascendant/Midheaven. Those need birth place, not just time; this package is the geocentric sky, location-independent. House systems belong in the consuming app.
• No domain interpretation. Gate wheels, sign rulers, dignities, aspects, card power — all live in the apps that consume these longitudes.

Continuously verified against JPL

The accuracy above is not a one-time claim. Two layers keep it true:

• Offline golden suite (positions.golden.test.ts) runs in every PR against baked JPL Horizons fixtures — fast, network-free, catches any regression.
• Weekly live calibration (.github/workflows/ephemeris-calibration.yml) scores the engine against live JPL Horizons across the full supported range (1900–2049) plus 2050+ watch points, so ΔT drift and orbital-element aging surface the week they appear. On any in-range breach it fails and files an issue.

Both check the same public contract, ACCURACY_TOLERANCE_ARCSEC (exported from the package) — so the offline suite can never be looser than the live one, and any engine change that widens the envelope must change that number in the same commit, in plain sight.

Run it yourself:

npm run calibrate           # score vs live JPL, exit 1 on drift
npm run calibrate:refresh   # regenerate baked fixtures from live JPL (deliberate)

Versioning

EPHEMERIS_VERSION is exported. Stamp it onto any persisted chart (ephemeris_version) so a future correction stays auditable: you can always answer "which engine drew this chart?".