Caelis Engine

Engine v4.0.12 · Schema v3.1 — these are independent version numbers. Schema v3.1 defines the output contract and is stable across engine patches.

v4.0.8 fixes an arcminute→degree unit error in atmospheric refraction that inflated alt_apparent_deg. Versions ≤ 4.0.7 are affected — upgrade. See CHANGELOG.md.

v4.0.10 makes getSnapshot() (in addition to getSnapshotAt()) fully independent of the wall clock within a single call, so every time-derived field in one snapshot refers to the exact same instant. Also corrects the declared Moon distance term count (29R, not 60R) and a broken import example. No changes to any other astronomical calculation.

v4.0.11 is a documentation and metadata release: merges a duplicated CHANGELOG entry, fixes a stale Moon term count and a Delta-T/UT1/UTC inconsistency in the technical spec, and clarifies that precision figures are algorithmic bounds of the underlying models, not measured implementation accuracy. Only a header comment (contact email) changed in core/CaelisEngine.js; no calculation was modified.

v4.0.12 fixes _sunLonAtJDE() (used for equinox/solstice search), the last remaining function that read the real wall clock instead of the shared frozen-clock mechanism introduced in 4.0.10. Verified with 18,000+ wall-clock-independence measurements (validation/scientific/clock-stress.js). Also corrects five ΔT/UT1/Moon-term documentation inconsistencies found during this fix. No change to any other astronomical calculation.

Every number this engine produces can be traced back to a known astronomical model, with declared precision and zero hidden assumptions.

Caelis Engine is a deterministic computation engine for celestial data. It replaces opaque APIs and black-box calculations with a fully auditable, reproducible, self-contained system — running entirely in the browser or Node.js, with no server, no API key, no ephemeris files, and no dependencies.

{
  "schema_version": "3.1",
  "meta": {
    "jd_tt": 2461193.499437,
    "frame": {
      "planets":  "VSOP87B (Bretagnon & Francou 1987)",
      "moon":     "ELP/MPP02-LLR · 164L+105B+29R terms",
      "nutation": "IAU 2000B · 77 luni-solar terms"
    }
  },
  "bodies": {
    "Sol":     { "lon_ecl_geocentric_deg": 71.498, "alt_geometric_deg": -27.896, "above_horizon": false },
    "Luna":    { "lon_ecl_geocentric_deg": 269.330, "lon_ecl_topocentric_deg": 270.082, "dist_km": 388954 },
    "Jupiter": { "lon_ecl_geocentric_deg": 114.254, "alt_geometric_deg": 8.267, "above_horizon": true }
  }
}

The problem

Most platforms working with celestial data rely on:

• Third-party APIs with opaque internal logic
• Results that cannot be audited or reproduced independently
• Infrastructure costs that scale with usage
• A dependency you don't control — and can't inspect

When something returns the wrong number, you have no way to know why. When the API changes, your product breaks. When the service goes down, so do you.

The solution

Caelis Engine gives you full ownership of your celestial computation layer.

• Deterministic — same input, same output. Always. Provably.
• Auditable — every algorithm declared in meta.frame. Every number traceable to its source.
• Self-contained — runs in the browser, in Node.js, in edge functions, offline. No backend required.
• Schema-stable — versioned JSON outputs with long-term compatibility guarantees.
• Zero dependencies — one JavaScript file. No install, no build step, no network.

This is not an API. It is a protocol — with a contract, invariants, and verifiable guarantees.

It is what products are built on.

Who builds with Caelis Engine

Astrology applications — birth charts, transits, synastry, progressions. Real planetary positions without subscription costs or rate limits. Runs 100% offline on the user's device. No data leaves the client.

Astronomy and educational tools — observational planning, sky simulators, interactive planetariums. Deterministic output means reproducible results across every device, every run.

AI pipelines and data infrastructure — any system where celestial data must be consistent, traceable, and unambiguous. A disabled plugin does not exist in the JSON. No null fields, no implicit states.

Games and interactive experiences — procedural sky systems, lunar calendar logic, celestial mechanics. Single-file distribution. Works offline. No build step required.

Architecture

TimeEngine → AstroCore → [ A.T.A.C.I.R. (optional) ]

Three layers. One direction. Strict separation of concerns.

TimeEngine

The only module that reads Date.now(). Computes JD, ΔT, GAST, LST, observer state. Every other module receives time as an explicit parameter.

AstroCore

Receives time from TimeEngine. Computes the physical state of the solar system. Returns a pure astronomical snapshot — schema v3.1.

Zero interpretive concepts. No houses. No aspects. No symbolic content. The engine does not interpret the sky. It measures it.

A.T.A.C.I.R. — interpretive layer

Arc-based Transformation of Astronomical Coordinates for Interpretive Resolution.

Architecturally separate from the astronomical core by design. Receives the snapshot. Appends derived computations under result.atacir.*. Never modifies the astronomical data.

Available plugins: houses · aspects · symmetries · lunar · cycles · resonances · panchanga · synastry · eclipses · directions

A disabled plugin does not exist in the JSON.

What it computes

Precision figures below are the algorithmic bounds published for each underlying astronomical model (VSOP87B, ELP/MPP02-LLR, etc.) - not a measurement of this implementation's accuracy. Caelis Engine's own validated implementation accuracy is documented, with methodology and results, in docs/SCIENTIFIC_VALIDATION.md.

| Computation | Algorithm | Algorithmic precision bound | |---|---|---| | Planets Mercury–Neptune | VSOP87B (Bretagnon & Francou 1987) | < 1′ | | Moon position | ELP/MPP02-LLR · 164L+105B+29R terms | < 10″ | | Nutation | IAU 2000B · 77 luni-solar terms | < 1 mas | | Obliquity | IAU 2006 (Capitaine et al.) | < 0.001° | | Light-time correction | Iterative · C = 173.14 AU/day | — | | Annual aberration | κ = 9.9365×10⁻⁵ rad | — | | Lunar parallax | Full topocentric · WGS-84 | max ~57′ | | Atmospheric refraction | Sæmundsson (1986) · inverse of Bennett (1982), agrees within ~0.1′ · ISA atmosphere | ±0.1′ > 15° | | ΔT | IERS table 500–2150 AD + Morrison-Stephenson | — | | Sidereal time | GAST IAU 2006 | ~15″ RMS (JD_TT simplification, see SCIENTIFIC_VALIDATION.md) | | Lunar nodes | Meeus Ch.47 | — |

Every snapshot contains both geometric and apparent altitude. Every field names its own coordinate frame. Every algorithm is declared in meta.frame.

Installation

npm install caelis-engine

Or download the single-file reference implementation: caelis-minimal.html — open with any local server, no install required.

API modes:

• setObserver() + getSnapshot() — stateful convenience API. Observer configured once, called repeatedly. Not pure in the functional sense — depends on global state.
• getSnapshotAt(jd_tt, observer) — explicit deterministic API. No global state. Same arguments always produce the same output.

Quick start

Option A — Single file (recommended)

Download dist/caelis-minimal.html. Open with a local server:

python -m http.server 8080
# open http://localhost:8080/caelis-minimal.html

No installation. No dependencies. No build step.

Option B — Node.js or bundler

import { getSnapshot, getSnapshotAt, setObserver }
  from 'caelis-engine';

// Set observer — Santiago, Chile
setObserver(-33.45, -70.66);

// Current celestial state
const snapshot = getSnapshot();

console.log(snapshot.bodies.Sol.lon_ecl_geocentric_deg);  // ecliptic longitude
console.log(snapshot.bodies.Sol.alt_geometric_deg);       // geometric altitude
console.log(snapshot.bodies.Luna.dist_km);                // lunar distance
console.log(snapshot.meta.obliquity.true_deg);            // true obliquity
console.log(snapshot.meta.frame.planets);                 // algorithm declaration

Option C — Any epoch, any location

// J2000.0 from London — fully deterministic
const j2000 = getSnapshotAt(2451545.0, { lat_deg: 51.5, lon_deg: -0.1 });

// 1987-Apr-10 from Paris — Meeus Ch.25 reference epoch
const meeus = getSnapshotAt(2446895.5, { lat_deg: 48.8, lon_deg: 2.3 });

Option D — A.T.A.C.I.R. Cloud

import { AtacirClient } from 'caelis-engine/client';

const client   = new AtacirClient({ apiKey: 'your-key' });
const snapshot = getSnapshot();
const result   = await client.compute(snapshot, {
  plugins: ['houses', 'aspects', 'panchanga']
});

console.log(result.atacir.houses.asc);          // Ascendant
console.log(result.atacir.aspects.natales[0]);  // strongest natal aspect
console.log(result.atacir.panchanga.tithiName); // Vedic almanac
// result.atacir.signature — R1-R5 integrity certification

Output schema v3.1

The schema is the contract. Stable, versioned, and guaranteed not to break between minor releases.

{
  "schema_version": "3.1",
  "meta": {
    "jd_tt":       2461193.499437,
    "jd_utc":      2461193.498611,
    "utc":         "2026-06-01T23:58:00Z",
    "delta_t_sec": 69.19,
    "observer":    { "lat_deg": -33.45, "lon_deg": -70.66 },
    "frame": {
      "nutation":                "IAU 2000B (77 luni-solar terms, Mathews et al. 2002)",
      "obliquity":               "IAU 2006 (Capitaine et al. 2006)",
      "planets":                 "VSOP87B (Bretagnon & Francou 1987) + Meeus App.II",
      "moon":                    "ELP/MPP02-LLR (Chapront & Francou 2002) 164L+105B+29R",
      "above_horizon_criterion": "geometric (unrefracted)"
    },
    "sidereal":  { "gast_deg": 250.278, "lst_deg": 179.618 },
    "obliquity": { "mean_deg": 23.4358, "true_deg": 23.4383 },
    "nutation":  { "delta_psi_arcsec": 8.271, "delta_eps_arcsec": 8.816 }
  },
  "bodies": {
    "Sol": {
      "ra_deg":                 69.958,
      "dec_deg":                22.160,
      "lon_ecl_geocentric_deg": 71.498,
      "lat_ecl_geocentric_deg": -0.00011,
      "alt_geometric_deg":      -27.896,
      "alt_apparent_deg":       -27.896,
      "az_deg":                 279.309,
      "above_horizon":          false,
      "dist_au":                1.01404
    },
    "Luna": {
      "lon_ecl_geocentric_deg":  269.330,
      "lon_ecl_topocentric_deg": 270.082,
      "alt_geometric_deg":       14.381,
      "alt_apparent_deg":        14.445,
      "dist_km":                 388954
    }
  },
  "luna": {
    "phase_ratio":  0.894,
    "phase_deg":    160.98,
    "illumination": 0.972
  }
}

Full schema: docs/CAELIS_ENGINE_SPEC_v4_0.md

Why not a third-party API or Swiss Ephemeris?

| | Third-party APIs | Swiss Ephemeris | Caelis Engine | |---|:---:|:---:|:---:| | Runs in browser | ✗ | ✗ | ✓ | | No server required | ✗ | ✗ | ✓ | | No API key or cost | ✗ | ✓ | ✓ | | Declared precision per field | ✗ | partial | ✓ | | Algorithm named in every output | ✗ | ✗ | ✓ | | Single JS file · no install | ✗ | ✗ | ✓ | | Offline capable | ✗ | ✓ | ✓ | | Schema-stable versioned output | ✗ | ✗ | ✓ | | Interpretive layer optional | N/A | N/A | ✓ |

Third-party APIs add latency, cost, and a dependency you don't control. Swiss Ephemeris is the precision standard — but it requires a server, a C wrapper, and ephemeris files.

Caelis Engine runs where neither can: directly in the browser, in edge functions, in React Native, in any JavaScript environment. Offline. Deterministically.

Validation

node validation/run.js
# 31 assertions · 6 groups · 0 failures

| Epoch | Source | Assertions | |---|---|---| | J2000.0 — 2000-Jan-01 12:00 TT | IAU SOFA + VSOP87 paper | 6 | | 1987-Apr-10 (Meeus Ch.25) | Meeus Astronomical Algorithms 2nd ed. | 4 | | 1992-Apr-12 (Meeus Ch.33 Venus) | VSOP87 verification table | 1 | | 2026-Jun-01 regression baseline | Caelis v4.0 canonical output | 8 | | Schema v3.1 invariants | Architecture contract | 9 | | Atmospheric refraction regression (v4.0.8) | Sæmundsson formula, arcmin→deg | 3 |

Precision and limitations

Designed for portability and auditability — not sub-arcsecond astrometry.

| Source | Declared max error | |---|---| | VSOP87B (Uranus, Neptune) | < 1′ | | ELP/MPP02 (Moon) | < 10″ | | IAU 2000B nutation | < 1 mas | | Refraction near horizon | 1–5′ | | ΔT outside 500–2150 AD | variable |

For sub-arcsecond requirements, use JPL Horizons or Swiss Ephemeris with full VSOP87. For everything that needs to run in a browser, offline, and deterministically — this is it.

A.T.A.C.I.R. Cloud

The interpretive layer is available as a managed API through Hermetica Labs.

What it adds on top of the astronomical core: house systems · natal and transit aspects · ecliptic symmetries · primary directions · lunar apsides and cycles · orbital resonances · Vedic Panchanga · synastry · eclipse prediction · R1-R5 Digital Signature

The R1-R5 Digital Signature is a cryptographic certification that the output was produced under the full Plugin Contract and has not been modified. Every result is auditable, traceable, and independently verifiable.

The computation logic is proprietary and server-side. The client is open source: client/AtacirClient.js

Early access: [email protected]

License

Caelis Engine is released under AGPL-3.0.

Free to use in open source software under AGPL-3.0 terms. If you are building a commercial or proprietary product, you need a commercial license.

Commercial licensing: [email protected] Details: COMMERCIAL_LICENSE.md

About

Caelis Engine was built by Cristian Valeria Bravo under Hermetica Labs.

Two principles guided every decision:

Compute the sky, not interpret it. AstroCore measures physical state. A.T.A.C.I.R. derives geometric meaning — only when asked, only in its own namespace, never modifying the astronomical truth.

Zero hidden assumptions. Every number is traceable. Every algorithm is declared. Every output is reproducible.

Caelis Engine is not the product. It is what products are built on.

Caelis Engine v4.0.12 · Hermetica Labs · © 2024–2026 Cristian Valeria Bravo