caelus-birth 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# caelus-birth
+
+Local birth time + place → UT, correctly. The timezone layer for
+[caelus](https://github.com/heavyblotto/caelus) charts.
+
+## The trap this package exists for
+
+caelus takes UT. Users state local wall-clock time. The naive conversion
+uses the *runtime's* timezone and is the single most common cause of wrong
+charts in amateur astrology software:
+
+```ts
+// WRONG — interprets "14:30" in whatever zone the server/browser runs in
+const d = new Date("1990-06-10T14:30:00");
+engine.chart(d.getUTCFullYear(), /* ... */);
+// Tampa birth computed on a UTC server: Asc 10°54' Leo  ← wrong by ~2 signs
+
+// RIGHT — resolve the zone from the birthplace, apply historical tzdb rules
+import { toUT } from "caelus-birth";
+const t = toUT({ year: 1990, month: 6, day: 10, hour: 14, minute: 30,
+                 lat: 27.95, lon: -82.46 });
+// zone "America/New_York", EDT, 18:30 UT → Asc 3°26' Libra  ← correct
+```
+
+Four hours of error moves the Ascendant ~60°, every house cusp with it,
+and (here) the Moon by 2°.
+
+## Usage
+
+```ts
+import { toUT, localToChart } from "caelus-birth";
+
+const t = toUT({
+  year: 1955, month: 6, day: 10, hour: 12, minute: 0,
+  lat: 51.5, lon: -0.12,          // east-positive longitude
+  // zone: "Europe/London"        // optional IANA override
+});
+t.utc;            // { year: 1955, month: 6, day: 10, hour: 11, ... } (BST +1)
+t.jdUt;           // ready for engine.chart() / engine.position()
+t.zone;           // "Europe/London" — resolved offline from coordinates
+t.offsetMinutes;  // 60
+t.dst;            // true
+t.status;         // "ok" | "ambiguous" | "nonexistent"
+
+// or in one call:
+const { chart, status } = localToChart(input, engine, "placidus");
+```
+
+### DST edge cases are reported, never guessed silently
+
+- **`"ambiguous"`** — the fall-back hour happens twice (e.g. 01:30 on the
+  night US DST ends). Both readings are returned in `candidates`
+  (earliest first) and the earlier instant is chosen by default. Surface
+  this to the user: "clocks changed that night — we used the earlier
+  01:30; switch?"
+- **`"nonexistent"`** — the spring-forward gap (e.g. 02:30 the night US
+  DST starts never existed). Shifted forward per tzdb convention
+  (02:30 EST → 03:30 EDT) and flagged.
+
+Historical rules come from the runtime's IANA database (via Luxon /
+`Intl`): half-hour and 45-minute zones, southern-hemisphere DST, pre-1970
+rules, and wartime offsets (British Double Summer Time, US War Time) all
+resolve correctly — see the golden tests.
+
+## Geocoding (optional, separate entry point)
+
+Place-name search needs a network service, so the core stays offline-pure
+and adapters live behind `caelus-birth/geocode`:
+
+```ts
+import { openMeteoGeocoder } from "caelus-birth/geocode";
+const places = await openMeteoGeocoder.search("Tampa");
+// [{ name: "Tampa, Florida, United States", lat: 27.95, lon: -82.46, ... }]
+```
+
+The shipped adapter uses the free, keyless
+[Open-Meteo Geocoding API](https://open-meteo.com/en/docs/geocoding-api)
+(data: [GeoNames](https://www.geonames.org/), CC-BY 4.0 — attribution
+required). Implement the one-method `Geocoder` interface to use any other
+service.
+
+## Scope
+
+Coordinates → zone is offline (`tz-lookup`, ~70 KB embedded map, CC0).
+Zone → offset uses the runtime's Intl tzdb (Luxon, MIT). This package has
+runtime dependencies by design; caelus core stays at zero.

package/dist/src/geocode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Optional geocoding entry point — `caelus-birth/geocode`.
+ *
+ * The core package is offline-pure; place-name search needs a network
+ * service, so it lives behind this separate entry point. One adapter ships
+ * (Open-Meteo: free, no key, attribution required — see README). Implement
+ * `Geocoder` to plug in any other service.
+ */
+export interface GeocodeResult {
+    /** Display name, e.g. "Tampa, Florida, United States". */
+    name: string;
+    lat: number;
+    /** EAST positive. */
+    lon: number;
+    country?: string;
+    admin1?: string;
+    /** IANA zone as reported by the service; pass as `zone` to toUT to skip
+     *  the coordinate lookup. */
+    timezone?: string;
+}
+export interface Geocoder {
+    search(query: string, limit?: number): Promise<GeocodeResult[]>;
+}
+/** https://open-meteo.com/en/docs/geocoding-api — free, no API key. */
+export declare const openMeteoGeocoder: Geocoder;

package/dist/src/geocode.js

@@ -0,0 +1,27 @@
+/**
+ * Optional geocoding entry point — `caelus-birth/geocode`.
+ *
+ * The core package is offline-pure; place-name search needs a network
+ * service, so it lives behind this separate entry point. One adapter ships
+ * (Open-Meteo: free, no key, attribution required — see README). Implement
+ * `Geocoder` to plug in any other service.
+ */
+/** https://open-meteo.com/en/docs/geocoding-api — free, no API key. */
+export const openMeteoGeocoder = {
+    async search(query, limit = 5) {
+        const url = "https://geocoding-api.open-meteo.com/v1/search?name="
+            + encodeURIComponent(query) + `&count=${limit}&language=en&format=json`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`open-meteo geocoding failed: HTTP ${res.status}`);
+        const data = (await res.json());
+        return (data.results ?? []).map((r) => ({
+            name: [r.name, r.admin1, r.country].filter(Boolean).join(", "),
+            lat: r.latitude,
+            lon: r.longitude,
+            country: r.country,
+            admin1: r.admin1,
+            timezone: r.timezone,
+        }));
+    },
+};

package/dist/src/index.d.ts

@@ -0,0 +1,53 @@
+import type { Engine, Chart, HouseSystem } from "caelus";
+export interface BirthInput {
+    /** Local calendar date as the person would state it. */
+    year: number;
+    month: number;
+    day: number;
+    /** Local clock time (24h). */
+    hour: number;
+    minute: number;
+    /** Latitude, north positive. */
+    lat: number;
+    /** Longitude, EAST positive (Americas are negative). */
+    lon: number;
+    /** Optional IANA zone override, e.g. "America/New_York". When omitted,
+     *  resolved from coordinates (offline, via tz-lookup). */
+    zone?: string;
+}
+export interface UTCandidate {
+    jdUt: number;
+    offsetMinutes: number;
+    dst: boolean;
+}
+export interface UTResult {
+    utc: {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
+    };
+    /** Julian Day (UT) — pass straight to engine.chart()/position(). */
+    jdUt: number;
+    /** Resolved IANA zone id. */
+    zone: string;
+    /** Offset applied, minutes east of UTC. */
+    offsetMinutes: number;
+    dst: boolean;
+    /**
+     * "ok"          — the wall-clock time maps to exactly one instant.
+     * "ambiguous"   — fall-back hour occurs twice; both candidates returned,
+     *                 the EARLIER instant chosen.
+     * "nonexistent" — spring-forward gap; shifted forward per tzdb
+     *                 convention (e.g. 02:30 EST -> 03:30 EDT), flagged.
+     */
+    status: "ok" | "ambiguous" | "nonexistent";
+    candidates?: UTCandidate[];
+}
+export declare function toUT(input: BirthInput): UTResult;
+/** toUT + engine.chart in one call. */
+export declare function localToChart(input: BirthInput, engine: Engine, houseSystem?: HouseSystem): UTResult & {
+    chart: Chart;
+};

package/dist/src/index.js

@@ -0,0 +1,107 @@
+/**
+ * caelus-birth — local birth time + place -> UT, correctly.
+ *
+ * caelus core takes UT. Real users enter local wall-clock time. The naive
+ * conversion (`new Date(localString)`) uses the RUNTIME's timezone and
+ * silently produces charts wrong by hours. This package resolves the IANA
+ * zone from coordinates (offline), applies the historical tzdb rules via
+ * the runtime's Intl database, and reports DST-transition edge cases
+ * (ambiguous fall-back times, nonexistent spring-forward times) instead of
+ * guessing silently.
+ *
+ * This package is allowed runtime dependencies (tz-lookup, luxon);
+ * caelus core stays at zero.
+ */
+import tzLookup from "tz-lookup";
+import { DateTime } from "luxon";
+import { julianDay } from "caelus";
+const MIN = 60_000;
+/** Zone offset (minutes east of UTC) at a UTC instant. */
+function offsetAt(ms, zone) {
+    return DateTime.fromMillis(ms, { zone }).offset;
+}
+function utcParts(ms) {
+    const d = new Date(ms);
+    return {
+        year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate(),
+        hour: d.getUTCHours(), minute: d.getUTCMinutes(), second: d.getUTCSeconds(),
+    };
+}
+function toJdUt(ms) {
+    const u = utcParts(ms);
+    return julianDay(u.year, u.month, u.day, u.hour, u.minute, u.second);
+}
+export function toUT(input) {
+    const { year, month, day, hour, minute, lat, lon } = input;
+    if (!(month >= 1 && month <= 12))
+        throw new Error(`Invalid month: ${month}`);
+    if (!(day >= 1 && day <= 31))
+        throw new Error(`Invalid day: ${day}`);
+    if (!(hour >= 0 && hour <= 23))
+        throw new Error(`Invalid hour: ${hour}`);
+    if (!(minute >= 0 && minute <= 59))
+        throw new Error(`Invalid minute: ${minute}`);
+    if (!(lat >= -90 && lat <= 90))
+        throw new Error(`Invalid latitude: ${lat}`);
+    if (!(lon >= -180 && lon <= 180))
+        throw new Error(`Invalid longitude: ${lon}`);
+    const zone = input.zone ?? tzLookup(lat, lon);
+    if (!DateTime.utc().setZone(zone).isValid) {
+        throw new Error(`Unknown IANA time zone: ${zone}`);
+    }
+    // Wall-clock time encoded as if it were UTC; candidate instants are
+    // wallMs - offset for each plausible offset around that moment.
+    const wallMs = DateTime.utc(year, month, day, hour, minute).toMillis();
+    if (Number.isNaN(wallMs))
+        throw new Error(`Invalid date: ${year}-${month}-${day}`);
+    // Offsets observed within a day either side cover any transition that
+    // could make this wall time ambiguous or nonexistent (gaps/overlaps are
+    // at most a few hours; offsets are bounded by ±14 h).
+    const probed = [wallMs - 86_400_000, wallMs, wallMs + 86_400_000]
+        .map((p) => offsetAt(p, zone));
+    const offsets = [...new Set(probed)];
+    // An offset is a valid reading iff applying it lands on an instant where
+    // the zone actually uses that offset.
+    const valid = offsets.filter((o) => offsetAt(wallMs - o * MIN, zone) === o);
+    // Pre-standardization (LMT-era) offsets carry seconds, so offset minutes
+    // can be fractional; round the conversion to whole milliseconds.
+    const result = (msRaw, status) => {
+        const ms = Math.round(msRaw);
+        const off = offsetAt(ms, zone);
+        return {
+            utc: utcParts(ms),
+            jdUt: toJdUt(ms),
+            zone,
+            offsetMinutes: off,
+            dst: DateTime.fromMillis(ms, { zone }).isInDST,
+            status,
+        };
+    };
+    if (valid.length === 1)
+        return result(wallMs - valid[0] * MIN, "ok");
+    if (valid.length >= 2) {
+        // fall-back overlap: the same wall time happened twice
+        const candidates = valid
+            .map((o) => Math.round(wallMs - o * MIN))
+            .sort((a, b) => a - b)
+            .map((ms) => ({
+            jdUt: toJdUt(ms),
+            offsetMinutes: offsetAt(ms, zone),
+            dst: DateTime.fromMillis(ms, { zone }).isInDST,
+        }));
+        return { ...result(wallMs - Math.max(...valid) * MIN, "ambiguous"), candidates };
+    }
+    // spring-forward gap: shift forward per tzdb convention by applying the
+    // offset in effect just before the gap (e.g. 02:30 EST -> 03:30 EDT)
+    const offBefore = offsetAt(wallMs - 86_400_000, zone);
+    return result(wallMs - offBefore * MIN, "nonexistent");
+}
+/** toUT + engine.chart in one call. */
+export function localToChart(input, engine, houseSystem = "placidus") {
+    const t = toUT(input);
+    const { year, month, day, hour, minute, second } = t.utc;
+    return {
+        ...t,
+        chart: engine.chart(year, month, day, hour, minute, second, input.lat, input.lon, houseSystem),
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "caelus-birth",
+  "version": "0.1.0",
+  "description": "Local birth time + place -> UT, correctly. IANA timezone resolution for caelus charts: DST, half-hour zones, ambiguous and nonexistent times.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node dist/test/golden.test.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "caelus": "^0.1.0",
+    "luxon": "^3.7.2",
+    "tz-lookup": "^6.1.25"
+  },
+  "devDependencies": {
+    "@types/luxon": "^3.7.1",
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./geocode": {
+      "types": "./dist/src/geocode.d.ts",
+      "default": "./dist/src/geocode.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heavyblotto/caelus.git",
+    "directory": "packages/birth"
+  },
+  "homepage": "https://ephemengine.com",
+  "keywords": [
+    "astrology",
+    "timezone",
+    "birth-time",
+    "iana",
+    "tzdb",
+    "natal-chart"
+  ]
+}