caelus 0.2.1 → 0.4.0

package/README.md

@@ -6,11 +6,12 @@ ephemeris files. 1:1 port of the Python reference, checked by golden fixtures.
 ## Verification chain
 
 1. Python engine checked against Swiss Ephemeris 2.10 across 1900–2099:
-   every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, nodes ≤ 1″
+   every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, mean node ≤ 1″,
+   true node ≤ 1′ vs SE's built-in ephemeris (≤ 1″ vs JPL DE431)
    (vs full DE431 files, 1850–2149), angles and Placidus cusps ≤ 3.2″ — all
    invisible at the arcminute display precision chart software uses.
-2. TypeScript port verified against Python golden fixtures: **1,438 checks,
-   0 failures, worst deviation 0.82 nano-arcseconds.** The two implementations
+2. TypeScript port verified against Python golden fixtures: **3,177 checks,
+   0 failures, worst deviation 1.64 nano-arcseconds.** The two implementations
    are numerically identical.
 
 Regenerate fixtures any time from the Python side; any future TS change must
@@ -62,8 +63,15 @@ engine.longitude("chiron", 2451545.0);
 engine.position("mars", 2451545.0); // { lon, speed, retrograde, sign, signDeg }
 ```
 
-Bodies: sun, moon, mercury…pluto, chiron, mean_node, true_node.
-House systems: placidus, porphyry, equal, whole_sign.
+Bodies: sun, moon, mercury…pluto, chiron, mean_node, true_node; on request:
+mean_lilith, true_lilith, ceres, pallas, juno, vesta, pholus, and the eight
+Hamburg-school Uranian bodies (cupido…poseidon) when their data packs are
+loaded.
+House systems: placidus, porphyry, equal, whole_sign, koch, regiomontanus,
+campanus, alcabitius, morinus, meridian, polich_page, vehlow (Placidus and
+Koch fall back to whole_sign above the polar circles).
+Event search: rise/set/meridian transits, zodiac crossings, lunar phases,
+stations (`events.ts`).
 Performance: ~2.4 ms per full chart (13 bodies × 3 evaluations + houses +
 aspects) single-threaded in Node 22 — ~420 charts/sec, faster in hot loops.
 
@@ -92,4 +100,4 @@ test/golden.test.ts  conformance suite vs Python fixtures
 - caelus — this package
 - [caelus-birth](https://www.npmjs.com/package/caelus-birth) — local birth time + place → UT (charts take UT; use this)
 - [caelus-wheel](https://www.npmjs.com/package/caelus-wheel) — React SVG chart wheel
-- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, six chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, seven chart tools over stdio

package/accuracy.json

@@ -3,30 +3,239 @@
   "range": "1900-2099",
   "unit": "arcsec",
   "bodies": [
-    { "name": "Sun", "max": "0.4", "rms": "0.2", "note": "" },
-    { "name": "Moon (precise tier)", "max": "2.5", "rms": "0.9", "note": "JPL DE423 fit (2010); DE423 vs DE440 is <0.1″ over this span" },
-    { "name": "Moon (embedded series)", "max": "9.6", "rms": "2.8", "note": "60-term ELP abridged" },
-    { "name": "Mercury", "max": "0.5", "rms": "0.2", "note": "" },
-    { "name": "Venus", "max": "0.8", "rms": "0.2", "note": "" },
-    { "name": "Mars", "max": "0.7", "rms": "0.2", "note": "" },
-    { "name": "Jupiter", "max": "0.9", "rms": "0.3", "note": "" },
-    { "name": "Saturn", "max": "0.8", "rms": "0.4", "note": "" },
-    { "name": "Uranus", "max": "1.9", "rms": "0.7", "note": "series truncation; complete VSOP87 holds ≤1″" },
-    { "name": "Neptune", "max": "4.6", "rms": "2.2", "note": "series truncation; complete VSOP87 holds ≤1″" },
-    { "name": "Pluto", "max": "2.5", "rms": "1.0", "note": "series valid 1885-2099" },
-    { "name": "Chiron", "max": "1.0", "rms": "0.3", "note": "JPL Horizons fit, 1850-2150" },
-    { "name": "Mean node", "max": "0.1", "rms": "0.1", "note": "" },
-    { "name": "True node", "max": "0.8", "rms": "0.4", "note": "vs full DE431 files; Swiss’s built-in Moshier mode itself differs from DE431 by up to ~15″ here" },
-    { "name": "Ascendant / MC", "max": "3.2", "rms": "—", "note": "" },
-    { "name": "Placidus cusps (all 12)", "max": "3.2", "rms": "—", "note": "" }
+    {
+      "name": "Sun",
+      "max": "0.4",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Moon (precise tier)",
+      "max": "2.5",
+      "rms": "0.9",
+      "note": "JPL DE423 fit (2010); DE423 vs DE440 is <0.1″ over this span"
+    },
+    {
+      "name": "Moon (embedded series)",
+      "max": "9.6",
+      "rms": "2.8",
+      "note": "60-term ELP abridged"
+    },
+    {
+      "name": "Mercury",
+      "max": "0.5",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Venus",
+      "max": "0.8",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Mars",
+      "max": "0.7",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Jupiter",
+      "max": "0.9",
+      "rms": "0.3",
+      "note": ""
+    },
+    {
+      "name": "Saturn",
+      "max": "0.8",
+      "rms": "0.4",
+      "note": ""
+    },
+    {
+      "name": "Uranus",
+      "max": "1.9",
+      "rms": "0.7",
+      "note": "series truncation; complete VSOP87 holds ≤1″"
+    },
+    {
+      "name": "Neptune",
+      "max": "4.6",
+      "rms": "2.2",
+      "note": "series truncation; complete VSOP87 holds ≤1″"
+    },
+    {
+      "name": "Pluto",
+      "max": "2.5",
+      "rms": "1.0",
+      "note": "series valid 1885-2099"
+    },
+    {
+      "name": "Chiron",
+      "max": "1.0",
+      "rms": "0.3",
+      "note": "JPL Horizons fit, 1850-2150"
+    },
+    {
+      "name": "Mean node",
+      "max": "0.1",
+      "rms": "0.1",
+      "note": ""
+    },
+    {
+      "name": "True node",
+      "max": "0.8",
+      "rms": "0.4",
+      "note": "vs full JPL DE431 files; vs Swiss Ephemeris's BUILT-IN (Moshier) ephemeris expect up to ~1′ (measured: 50″ max, 8″ median, 300 epochs) — that is the built-in lunar theory's own node error, not ours"
+    },
+    {
+      "name": "Ascendant / MC",
+      "max": "3.2",
+      "rms": "—",
+      "note": ""
+    },
+    {
+      "name": "Placidus cusps (all 12)",
+      "max": "3.2",
+      "rms": "—",
+      "note": ""
+    },
+    {
+      "name": "Mean Lilith",
+      "max": "1.3",
+      "rms": "0.5",
+      "note": "mean lunar apogee on the inclined orbit; latitude ≤0.1″"
+    },
+    {
+      "name": "Sidereal longitudes",
+      "max": "0.1",
+      "rms": "—",
+      "note": "ayanamsa model vs SE ≤0.30″ at the 1900/2099 edges (IAU 1976 vs Vondrák precession); Sun worst-case 0.08″ at 120 sampled epochs"
+    },
+    {
+      "name": "RA / Dec",
+      "max": "2.1",
+      "rms": "—",
+      "note": "rotation is exact; bound tracks each body's ecliptic accuracy (Moon worst)"
+    },
+    {
+      "name": "Topocentric Moon",
+      "max": "2.7",
+      "rms": "—",
+      "note": "parallax model adds ≤0.1″ over the geocentric bound"
+    },
+    {
+      "name": "House cusps, 8 new systems",
+      "max": "0.0",
+      "rms": "0.0",
+      "note": "Koch, Regiomontanus, Campanus, Alcabitius, Morinus, Meridian, Polich-Page, Vehlow: exact vs swe_houses_armc (200 polar-inclusive cases each)"
+    },
+    {
+      "name": "Vertex / east point",
+      "max": "0.0",
+      "rms": "0.0",
+      "note": "exact vs swe_houses_armc"
+    },
+    {
+      "name": "Magnitudes",
+      "max": "0.045 mag",
+      "rms": "—",
+      "note": "Mallama 2018; Moon (Allen law) valid to phase angle 140°"
+    },
+    {
+      "name": "Rise/set/meridian transit",
+      "max": "0.5 s",
+      "rms": "—",
+      "note": "vs swe_rise_trans, 48 polar-inclusive cases per body; Moon bound tracks its position accuracy"
+    },
+    {
+      "name": "Crossings / lunar phases",
+      "max": "4 s",
+      "rms": "—",
+      "note": "vs swe_solcross/swe_mooncross and elongation root-finds"
+    },
+    {
+      "name": "Stations",
+      "max": "55 s",
+      "rms": "—",
+      "note": "ill-conditioned by nature: speed-zero slope ~0.01°/day² turns sub-arcsecond model differences into minutes"
+    },
+    {
+      "name": "True Lilith (osc. apogee)",
+      "max": "187",
+      "rms": "—",
+      "note": "hypersensitive to the lunar theory (~1/e amplification); SE's own Moshier-vs-DE difference dominates. 'True Lilith' values disagree across software at this scale"
+    },
+    {
+      "name": "Ceres, Pallas, Juno, Vesta, Pholus",
+      "max": "1.0",
+      "rms": "0.3",
+      "note": "JPL Horizons fits 1850-2150 (residual <5e-6 AU); same geocentric pipeline as Chiron. No independent SE oracle here: SE's asteroid files are unavailable in Moshier mode"
+    },
+    {
+      "name": "Uranian bodies (Cupido…Poseidon)",
+      "max": "2.3",
+      "rms": "—",
+      "note": "Hamburg-school constant-element Kepler orbits, elements fitted to SE 2.10's built-in definitions (fit_uranian.py prints per-body figures; Zeus is fit-noise-limited at ~3″ heliocentric). Uranian practice works in arcminutes"
+    }
   ],
   "summary": [
-    { "label": "Sun–Saturn", "bound": "≤ 1″" },
-    { "label": "Uranus / Neptune", "bound": "≤ 1.9″ / ≤ 4.6″" },
-    { "label": "Moon (1920–2080 tier)", "bound": "≤ 2.5″" },
-    { "label": "Moon (series, embedded)", "bound": "≤ 10″" },
-    { "label": "Pluto / Chiron", "bound": "≤ 2.5″ / ≤ 1″" },
-    { "label": "Angles & Placidus cusps", "bound": "≤ 3.2″" },
-    { "label": "True node", "bound": "≤ 1″" }
-  ]
-}
+    {
+      "label": "Sun–Saturn",
+      "bound": "≤ 1″"
+    },
+    {
+      "label": "Uranus / Neptune",
+      "bound": "≤ 1.9″ / ≤ 4.6″"
+    },
+    {
+      "label": "Moon (1920–2080 tier)",
+      "bound": "≤ 2.5″"
+    },
+    {
+      "label": "Moon (series, embedded)",
+      "bound": "≤ 10″"
+    },
+    {
+      "label": "Pluto / Chiron",
+      "bound": "≤ 2.5″ / ≤ 1″"
+    },
+    {
+      "label": "Angles & Placidus cusps",
+      "bound": "≤ 3.2″"
+    },
+    {
+      "label": "True node",
+      "bound": "≤ 1′ vs SE built-in (≤ 1″ vs JPL DE431)"
+    },
+    {
+      "label": "Mean Lilith",
+      "bound": "≤ 1.3″"
+    },
+    {
+      "label": "Sidereal (5 ayanamsas)",
+      "bound": "≤ 0.3″ added"
+    },
+    {
+      "label": "8 new house systems",
+      "bound": "exact (0.0″)"
+    },
+    {
+      "label": "Rise/set/transit",
+      "bound": "≤ 0.5 s"
+    },
+    {
+      "label": "Crossings & phases",
+      "bound": "≤ 4 s"
+    },
+    {
+      "label": "Asteroids (big 4 + Pholus)",
+      "bound": "≤ 1″"
+    },
+    {
+      "label": "Uranian bodies",
+      "bound": "≤ 2.3″"
+    }
+  ],
+  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)",
+  "true_node_vs_builtin": "1′"
+}

package/dist/src/chart.d.ts

@@ -1,17 +1,45 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
-import { EngineData } from "./core.js";
+import { EngineData, AYANAMSA_J2000 } from "./core.js";
 export declare const BODIES: readonly ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node"];
 export type Body = (typeof BODIES)[number];
+/** Computable on request (not in the default chart set). */
+export declare const EXTRA_BODIES: readonly ["mean_lilith", "true_lilith"];
+/** Core names keep autocomplete; any string id is accepted (data packs). */
+export type BodyId = Body | (typeof EXTRA_BODIES)[number] | (string & {});
 export declare const SIGNS: string[];
 export declare const ASPECTS: Record<string, number>;
 export declare const DEFAULT_ORBS: Record<string, number>;
-export type HouseSystem = "placidus" | "porphyry" | "equal" | "whole_sign";
+export type HouseSystem = "placidus" | "porphyry" | "equal" | "whole_sign" | "koch" | "regiomontanus" | "campanus" | "alcabitius" | "morinus" | "meridian" | "polich_page" | "vehlow";
+export type Ayanamsa = keyof typeof AYANAMSA_J2000 & string;
+export type Zodiac = "tropical" | `sidereal:${string}`;
+export interface Observer {
+    lat: number;
+    lonEast: number;
+    altM?: number;
+}
+export interface CalcOptions {
+    zodiac?: Zodiac;
+    topocentric?: boolean;
+    observer?: Observer;
+}
+export interface ChartOptions extends CalcOptions {
+    houseSystem?: HouseSystem;
+    bodies?: BodyId[];
+    orbs?: Record<string, number>;
+}
 export interface Position {
     lon: number;
     speed: number;
     retrograde: boolean;
     sign: string;
     signDeg: number;
+    /** Ecliptic latitude, deg (0 for nodes). */
+    lat: number;
+    /** Geocentric distance in AU (Moon included); null for nodes and Lilith. */
+    dist: number | null;
+    /** Equatorial coordinates, true equinox of date, deg. */
+    ra: number;
+    dec: number;
 }
 export interface Aspect {
     a: string;
@@ -21,30 +49,50 @@ export interface Aspect {
 }
 export interface Chart {
     jdUt: number;
-    /** House system actually used. May differ from the request: Placidus is
-     *  undefined above the polar circles and falls back to whole_sign. */
+    zodiac: Zodiac;
+    /** House system actually used. May differ from the request: Placidus and
+     *  Koch are undefined above the polar circles and fall back to whole_sign. */
     houseSystem: HouseSystem;
     houseSystemRequested: HouseSystem;
     bodies: Record<string, Position>;
     angles: {
         asc: number;
         mc: number;
+        vertex: number;
+        eastPoint: number;
     };
     cusps: number[];
     aspects: Aspect[];
 }
 export declare class Engine {
-    private data;
+    readonly data: EngineData;
     private moonCheb;
     private chironCheb;
+    private packs;
     constructor(data: EngineData);
+    private pack;
     private moonInRange;
-    /** Apparent geocentric ecliptic longitude (deg), true equinox of date. */
-    longitude(body: Body, jdUt: number): number;
-    /** Longitude (deg) + speed (deg/day) + retrograde flag. */
-    position(body: Body, jdUt: number): Position;
-    /** Full natal chart. Time is UT. East longitude positive. */
-    chart(y: number, mo: number, d: number, h: number, mi: number, s: number, lat: number, lonEast: number, houseSystem?: HouseSystem): Chart;
+    /** Body ids this engine can compute, given the data it was handed. */
+    bodies(): BodyId[];
+    /** Apparent geocentric [lon rad, lat rad, dist AU | null] at TT jde.
+     *  Building block for the events module; chart consumers want
+     *  position() instead. */
+    ecliptic(body: BodyId, jde: number): [number, number, number | null];
+    private lonOnly;
+    /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
+     *  of date. Sidereal: mean equinox minus ayanamsa. */
+    longitude(body: BodyId, jdUt: number, opts?: CalcOptions): number;
+    /** Geometric heliocentric ecliptic of date (deg, deg, AU). */
+    heliocentric(body: BodyId, jdUt: number): {
+        lon: number;
+        lat: number;
+        dist: number;
+    };
+    /** Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec. */
+    position(body: BodyId, jdUt: number, opts?: CalcOptions): Position;
+    /** Full natal chart. Time is UT. East longitude positive. The ninth
+     *  argument takes a house system name (0.2.x form) or a ChartOptions bag. */
+    chart(y: number, mo: number, d: number, h: number, mi: number, s: number, lat: number, lonEast: number, opts?: HouseSystem | ChartOptions): Chart;
 }
 export declare function findAspects(bodies: Record<string, Position>, orbs?: Record<string, number>): Aspect[];
 export declare function fmtLon(deg: number): string;