@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.

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.

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?".