@openephemeris/mcp-server 4.5.0 → 4.7.0

package/CHANGELOG.md

@@ -7,6 +7,110 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.7.0] — 2026-08-02
+
+Historically correct birth-time conversion. IANA timezone databases — including
+the one inside every JavaScript runtime — are only authoritative from 1970.
+Before the US Uniform Time Act took effect in 1967, daylight saving was state
+and municipal law, and a zone like `America/Chicago` models Chicago alone. A
+1961 Minnesota birth converted with standard timezone math lands an hour off,
+which flips the Ascendant sign and the Human Design design-Moon gate.
+
+### Added
+
+- **Pre-1970 births now resolve through the API's historical correction
+  overlay.** Any tool given a naive local birth time with a timezone and
+  coordinates — natal, Human Design (chart, composite, penta, cycles, groups),
+  Vedic, BaZi apps, ACG, moon tools, and the embedded chart apps — routes the
+  local→UTC conversion through the API's `/timezone/offset` `datetime_local`
+  mode, which applies primary-source-cited state and local law (with a
+  `tz_confidence` grade and rule citation) instead of assuming the reference
+  city's rules. Post-1970 conversions stay on the local, zero-latency path,
+  which is exactly as authoritative as the server. If the server is
+  unreachable, tools fall back to the previous local conversion rather than
+  failing the chart call.
+- **`timezone_resolve`** consults the same historical path for pre-1970 dates
+  and reports `tzConfidence`, `tzRuleSource`, and `datetimeStatus` (ambiguous
+  DST-fold and nonexistent-gap times are called out explicitly).
+- **`location_search`** tags each suggestion's historical offset with a
+  confidence grade and a note when a pre-1970 date may be affected by
+  state/local law divergence.
+
+### Fixed
+
+- Three skills and one prompt still instructed the model to convert local
+  birth times to UTC itself with generic timezone math — the exact manual
+  conversion the historical overlay exists to prevent. They now direct all
+  conversion through the API.
+
+---
+
+## [4.6.0] — 2026-07-30
+
+Fixes the tool that could not answer the question it is named for, closes the
+last two places a chart was silently computed at 0°N 0°E, and stops two tools
+discarding a timezone the caller supplied. The first three come from a 75-run
+behavioural eval (25 prompts × 3, fresh context each) run against 4.4.0; the
+last from the directory-submission readiness review.
+
+### Fixed
+
+- **`ephemeris_next_eclipse` can now find the next eclipse.** Without a
+  location it routed to `/eclipse/solar/global` or `/eclipse/lunar/global`,
+  which classify whatever eclipse is occurring *at* a given instant rather
+  than searching forward from one. The consequences compounded: `after_date`
+  was documented as optional and defaulting to today, but the backend
+  rejected the call without it; an ordinary date returned *"no solar eclipse
+  occurs at the requested date"*; and `eclipse_type: 'any'` was accepted and
+  ignored. Asking *"when is the next solar eclipse"* was unanswerable.
+
+  It now calls a new `/eclipse/next` endpoint that genuinely searches forward
+  from `after_date` (defaulting to now), honours `any` by returning whichever
+  of solar/lunar comes first, and needs no arguments beyond the type. Server
+  side in [`openephemeris#473`](https://github.com/openephemeris/openephemeris/pull/473).
+
+  Worth stating plainly, because it is the reason this is the lede: a broken
+  tool did not surface an error to the end user. Across three runs of the
+  same prompt the model answered from its own memory twice — once correctly,
+  once naming an eclipse in the wrong year — and disagreed with itself. Only
+  one run in three reported that the tool had failed.
+
+- **`explore_human_design_transit` and `explore_human_design_connection` no
+  longer silently compute at 0°N 0°E.** 4.4.0 fixed this for
+  `explore_human_design` and wired `location` into four chart tools; these
+  two were missed. `explore_human_design_transit` accepted a `location` that
+  was display-only — its own description conceded the chart would be cast on
+  the Gulf of Guinea — and `explore_human_design_connection` had no location
+  field at all for either person. Both now resolve a place name through the
+  same lookup `location_search` uses, and reject the call outright when
+  neither coordinates nor a resolvable location is supplied.
+
+- **`ephemeris_natal_batch` and `explore_transit_timeline` no longer discard a
+  supplied timezone.** Both declared a timezone parameter and then built the
+  request body without it, so a naive local birth time plus an IANA zone — the
+  remedy the server's own error message recommends — was rejected by the
+  datetime contract. `ephemeris_natal_batch` failed this way for *every*
+  subject in a batch, and its documented example was the failing shape;
+  `explore_transit_timeline` never read `natal_timezone` at all. Both now route
+  the value through the same canonical helper the rest of the surface uses, so
+  the zone reaches the wire.
+
+### Changed
+
+- **Two server-side fixes change what these tools return** (no MCP change
+  required, listed because the output differs):
+  `ephemeris_natal_chart` with `format: 'llm'` now distinguishes the mean and
+  true lunar nodes — both previously carried the id `north_node`, so a
+  consumer keying by id silently dropped one and the `aspects` indices
+  inherited the ambiguity ([`#475`](https://github.com/openephemeris/openephemeris/pull/475)).
+  And `server_version` in calculation metadata is now derived from the
+  deployed image reference rather than Fly's per-machine version counter, so
+  every instance serving a given release reports the same value; a separate
+  `instance_id` carries per-machine attribution
+  ([`#474`](https://github.com/openephemeris/openephemeris/pull/474)).
+
+---
+
 ## [4.5.0] — 2026-07-30
 
 Adds a tool for the question the astrocartography tools could not answer:

package/dist/prompts.js

@@ -377,8 +377,9 @@ export const PROMPTS = [
             "even 10–15 minutes can shift the Type, Authority, or Profile. If truly unknown, " +
             "proceed with solar noon but flag that results may be imprecise.\n" +
             "4. **Birth city and country** — needed for timezone conversion\n\n" +
-            "## Step 2 — CRITICAL: Convert to UTC\n" +
-            "Human Design requires **UTC datetime**. The tool rejects local times without a UTC offset.\n\n" +
+            "## Step 2 — Resolve Coordinates and Timezone\n" +
+            "Human Design needs the exact birth instant; the tool resolves it from local time + " +
+            "timezone + coordinates automatically (historically correct even pre-1970).\n\n" +
             "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
             "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
             "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +

package/dist/tools/apps/bodygraph-app.js

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
@@ -372,9 +372,9 @@ registerTool({
             location: args.location,
         });
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = resolved.latitude;
         const lon = resolved.longitude;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         if (lat == null || lon == null) {
             throw new Error("explore_human_design requires either `latitude` + `longitude` or a resolvable `location` name. " +
                 "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
@@ -473,10 +473,11 @@ registerTool({
     handler: async (args) => {
         const client = getActiveClient();
         const timezone = args.timezone;
-        // Convert local-time input → UTC using IANA timezone when provided
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        // Convert local-time input → UTC using IANA timezone when provided;
+        // pre-1970 births route through the API's historical correction overlay.
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const theme = args.theme === "light" ? "light" : "dark";
         const layout = args.layout === "mandala" ? "mandala" : undefined;
         const rings = typeof args.rings === "string" ? args.rings : undefined;
@@ -1319,9 +1320,9 @@ registerTool({
                 description: "Natal birth datetime, ISO 8601 (e.g. '1990-04-15T19:30:00Z'). Include 'Z' or an offset, " +
                     "or supply timezone for local time. HD is time-sensitive to the minute.",
             },
-            latitude: { type: "number", description: "Natal birth latitude (decimal degrees, +N). Optional." },
-            longitude: { type: "number", description: "Natal birth longitude (decimal degrees, +E). Optional." },
-            location: { type: "string", description: "Natal location name, display only. This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E." },
+            latitude: { type: "number", description: "Natal birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in." },
+            longitude: { type: "number", description: "Natal birth longitude in decimal degrees (positive = East). Optional if `location` is a place name." },
+            location: { type: "string", description: "Natal birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If neither location nor lat/lon is supplied the call is rejected — no silent 0°N 0°E charts." },
             timezone: { type: "string", description: "IANA timezone for the birth location (e.g. 'America/New_York')." },
             transit_datetime: {
                 type: "string",
@@ -1355,16 +1356,30 @@ registerTool({
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const timezone = args.timezone;
-        const natalIso = localToUtcIso("datetime", String(args.datetime), timezone);
-        const lat = args.latitude ?? 0;
-        const lon = args.longitude ?? 0;
+        // Resolve `location` → lat/lon/tz when the caller left coords unset.
+        // If neither is provided we throw rather than silently computing at
+        // 0°N 0°E (a plausible-looking chart nothing downstream can detect).
+        const resolved = await coordsFromArgsOrLocation({
+            latitude: args.latitude,
+            longitude: args.longitude,
+            timezone: args.timezone,
+            location: args.location,
+        });
+        const timezone = args.timezone ?? resolved.timezone;
+        const lat = resolved.latitude;
+        const lon = resolved.longitude;
+        const natalIso = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
+        if (lat == null || lon == null) {
+            throw new Error("explore_human_design_transit requires either `latitude` + `longitude` or a resolvable `location` name. " +
+                "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
+        }
+        const location = String(resolved.location ?? args.location ?? "Subject").slice(0, 120);
         // SubjectRequest wire shape: name (required), birth_datetime.iso, and
         // birth_location with struct-typed coordinate/timezone inputs (matches the
         // live bi-wheel/transit-timeline tools — bare scalars are rejected).
         const body = {
             subject: {
-                name: args.location ?? "Subject",
+                name: location,
                 birth_datetime: { iso: natalIso },
                 birth_location: {
                     latitude: { decimal: lat },
@@ -1375,7 +1390,7 @@ registerTool({
         };
         if (args.transit_datetime) {
             body.transit_datetime = {
-                iso: localToUtcIso("transit_datetime", String(args.transit_datetime), args.timezone),
+                iso: await localToUtcIsoHistorical("transit_datetime", String(args.transit_datetime), args.timezone, { latitude: lat, longitude: lon }),
             };
         }
         const bundleAvailable = Boolean(getBodygraphBundle());
@@ -1441,8 +1456,9 @@ registerTool({
                 description: "First person's birth data.",
                 properties: {
                     datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
-                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
-                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    latitude: { type: "number", description: "Birth latitude, decimal degrees (+N). Optional if `location` is set." },
+                    longitude: { type: "number", description: "Birth longitude, decimal degrees (+E). Optional if `location` is set." },
+                    location: { type: "string", description: "Birth location, e.g. 'New York, NY' — resolved like location_search (ambiguous names throw). Omitting both this and lat/lon rejects the call rather than defaulting to 0°N 0°E." },
                     timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
                 },
                 required: ["datetime"],
@@ -1452,8 +1468,9 @@ registerTool({
                 description: "Second person's birth data.",
                 properties: {
                     datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
-                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
-                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    latitude: { type: "number", description: "Birth latitude, decimal degrees (+N). Optional if `location` is set." },
+                    longitude: { type: "number", description: "Birth longitude, decimal degrees (+E). Optional if `location` is set." },
+                    location: { type: "string", description: "Birth location, e.g. 'New York, NY' — resolved like location_search (ambiguous names throw). Omitting both this and lat/lon rejects the call rather than defaulting to 0°N 0°E." },
                     timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
                 },
                 required: ["datetime"],
@@ -1486,17 +1503,32 @@ registerTool({
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const toSubject = (p, label) => {
-            const tz = p?.timezone;
+        // Resolve each person's `location` → lat/lon/tz when coords are unset.
+        // If neither is provided we throw rather than silently computing at
+        // 0°N 0°E (a plausible-looking chart nothing downstream can detect).
+        const toSubject = async (p, label) => {
+            const resolved = await coordsFromArgsOrLocation({
+                latitude: p?.latitude,
+                longitude: p?.longitude,
+                timezone: p?.timezone,
+                location: p?.location,
+            });
+            const tz = p?.timezone ?? resolved.timezone;
+            const lat = resolved.latitude;
+            const lon = resolved.longitude;
+            if (lat == null || lon == null) {
+                throw new Error(`${label} requires either \`latitude\` + \`longitude\` or a resolvable \`location\` name. ` +
+                    "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
+            }
             return {
-                birth_datetime_utc: localToUtcIso(`${label}.datetime`, String(p?.datetime), tz, `${label}.timezone`),
-                latitude: p?.latitude ?? 0,
-                longitude: p?.longitude ?? 0,
+                birth_datetime_utc: await localToUtcIsoHistorical(`${label}.datetime`, String(p?.datetime), tz, { latitude: lat, longitude: lon }, `${label}.timezone`),
+                latitude: lat,
+                longitude: lon,
             };
         };
         const body = {
-            subject_1: toSubject(args.person_a, "person_a"),
-            subject_2: toSubject(args.person_b, "person_b"),
+            subject_1: await toSubject(args.person_a, "person_a"),
+            subject_2: await toSubject(args.person_b, "person_b"),
         };
         const bundleAvailable = Boolean(getBodygraphBundle());
         // Mirror the transit tool: explicit dark default, host-theme refetch.

package/dist/tools/apps/location-tools.js

@@ -1,6 +1,15 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
+/** Render minutes east of UTC as `±HH:MM`. */
+function formatOffsetMinutes(offsetMinutes) {
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const abs = Math.abs(offsetMinutes);
+    const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+    const mm = String(Math.round(abs % 60)).padStart(2, "0");
+    return `${sign}${hh}:${mm}`;
+}
 /**
  * The UTC offset of an IANA zone is a function of place AND date: 1987 US DST
  * rules are not today's rules, and America/Chicago ran on CDT through the whole
@@ -143,6 +152,8 @@ registerTool({
         // Map the API's snake_case response to the camelCase shape the app UI consumes.
         const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
+        const dateYear = date ? Number(date.slice(0, 4)) : null;
+        const preTzdataEra = dateYear != null && Number.isFinite(dateYear) && dateYear < TZDATA_AUTHORITATIVE_FROM_YEAR;
         const suggestions = list.map((s) => {
             const mapped = {
                 displayName: s.display_name,
@@ -154,8 +165,17 @@ registerTool({
                 longitude: s.longitude,
                 timezone: s.timezone,
             };
-            if (date && s.timezone)
-                Object.assign(mapped, offsetAtLocalNoon(s.timezone, date) ?? {});
+            if (date && s.timezone) {
+                const offset = offsetAtLocalNoon(s.timezone, date);
+                if (offset) {
+                    // These offsets come from local tzdata, which is only
+                    // authoritative from 1970 — before that it models the
+                    // zone's reference city, not state/local law.
+                    Object.assign(mapped, offset, {
+                        tzConfidence: preTzdataEra ? "historical_estimate" : "authoritative",
+                    });
+                }
+            }
             return mapped;
         });
         // Ambiguity signal. "portland" really does match Oregon, Maine, Texas,
@@ -180,6 +200,11 @@ registerTool({
         return {
             suggestions,
             matchCount: suggestions.length,
+            ...(preTzdataEra
+                ? {
+                    historicalNote: "Pre-1970 date: tzdata offsets are reference-city estimates. For the chosen place, call timezone_resolve with the same date (or submit the naive local time + timezone + coordinates to the chart endpoint) to apply the API's historical correction overlay.",
+                }
+                : {}),
             ambiguous,
             ...(ambiguous
                 ? {
@@ -203,7 +228,7 @@ registerTool({
             longitude: { type: "number" },
             date: {
                 type: "string",
-                description: "Optional birth/event date as 'YYYY-MM-DD'. When given, the result also carries utcOffsetAtDate / utcOffsetMinutes / isDst for that date under that zone's historical DST rules. Free: adds no API call and no credits.",
+                description: "Optional birth/event date 'YYYY-MM-DD'. Adds utcOffsetAtDate / utcOffsetMinutes / isDst / tzConfidence. Post-1970 resolves locally (free); pre-1970 consults the API's historical correction overlay (1 extra credit).",
             },
         },
         required: ["latitude", "longitude"],
@@ -228,9 +253,46 @@ registerTool({
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
         const tz = typeof result?.timezone === "string" ? result.timezone : null;
         if (date && tz) {
+            // Pre-1970 dates: tzdata (Node's and Go's alike) models the zone's
+            // reference city only, so ask the API — its historical correction
+            // overlay knows where state law diverged (e.g. Minnesota 1959-66).
+            // Costs one extra credit, only for pre-1970 dates.
+            const year = Number(date.slice(0, 4));
+            if (Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR) {
+                try {
+                    const off = (await getActiveClient().request("POST", "/timezone/offset", {
+                        data: { lat: args.latitude, lon: args.longitude, datetime_local: `${date.slice(0, 10)}T12:00:00` },
+                    }));
+                    if (typeof off?.offset_seconds === "number") {
+                        const minutes = off.offset_seconds / 60;
+                        return {
+                            ...result,
+                            utcOffsetAtDate: formatOffsetMinutes(minutes),
+                            utcOffsetMinutes: minutes,
+                            isDst: Boolean(off.is_dst),
+                            date,
+                            tzConfidence: typeof off.tz_confidence === "string" ? off.tz_confidence : "historical_estimate",
+                            ...(typeof off.tz_rule_source === "string" ? { tzRuleSource: off.tz_rule_source } : {}),
+                            ...(typeof off.datetime_status === "string" ? { datetimeStatus: off.datetime_status } : {}),
+                        };
+                    }
+                }
+                catch {
+                    // Server path unavailable — fall through to the local
+                    // tzdata estimate below, flagged as such.
+                }
+            }
             const offset = offsetAtLocalNoon(tz, date);
-            if (offset)
-                return { ...result, ...offset, date };
+            if (offset) {
+                return {
+                    ...result,
+                    ...offset,
+                    date,
+                    tzConfidence: Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR
+                        ? "historical_estimate"
+                        : "authoritative",
+                };
+            }
         }
         return result;
     },

package/dist/tools/apps/moon-phase-app.js

@@ -17,7 +17,8 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
 export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -98,7 +99,7 @@ async function computeMoonData(args) {
     const client = getActiveClient();
     const params = {};
     params.datetime = args.datetime
-        ? localToUtcIso("datetime", String(args.datetime), args.timezone)
+        ? await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: args.latitude, longitude: args.longitude })
         : new Date().toISOString();
     if (args.latitude != null)
         params.latitude = args.latitude;

package/dist/tools/apps/transit-timeline-app.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
+import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty, toDateTimeInputBody } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
 export const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -150,10 +150,15 @@ registerTool({
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
         const client = getActiveClient();
         // ── Step 1: natal chart → real planetary longitudes ──────────────────────
+        // natal_timezone is a declared parameter — it must reach the wire body.
+        // It previously did not, so a caller following the server's own remedy for
+        // a naive datetime ("name the zone in the sibling `timezone` argument")
+        // had the zone silently dropped and got a 400 from the Go contract with no
+        // working alternative.
         const natalBody = {
             subject: {
                 name: "Transit Natal Subject",
-                birth_datetime: { iso: args.natal_datetime },
+                birth_datetime: toDateTimeInputBody("natal_datetime", String(args.natal_datetime), args.natal_timezone, "natal_timezone"),
                 birth_location: {
                     latitude: { decimal: args.natal_latitude },
                     longitude: { decimal: args.natal_longitude },

package/dist/tools/apps/vedic-chart-app.js

@@ -23,7 +23,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
@@ -165,9 +165,9 @@ registerTool({
         validateCoordinates(argsWithResolved, "latitude", "longitude");
         const client = getActiveClient();
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = Number(resolved.latitude);
         const lon = Number(resolved.longitude);
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const location = String(resolved.location ?? args.location ?? `${lat}, ${lon}`).slice(0, 120);
         const bundleAvailable = Boolean(getVedicChartBundle());
@@ -244,9 +244,9 @@ registerTool({
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const datetime = localToUtcIso("datetime", String(args.datetime), args.timezone);
         const lat = args.latitude != null ? Number(args.latitude) : undefined;
         const lon = args.longitude != null ? Number(args.longitude) : undefined;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const theme = args.theme === "light" ? "light" : "dark";
         const body = {

package/dist/tools/datetime-historical.d.ts

@@ -0,0 +1,19 @@
+/** Where IANA tzdata stops being reference-city best effort. */
+export declare const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
+export interface BirthCoords {
+    latitude?: number | null;
+    longitude?: number | null;
+}
+/** True when a naive local datetime needs the server-side historical path. */
+export declare function needsHistoricalResolution(dt: string, coords?: BirthCoords): boolean;
+/**
+ * `localToUtcIso`, but historically correct when it matters.
+ *
+ * Same contract as `localToUtcIso` (naive value with no `tz` throws the
+ * ambiguous-datetime error; zone-suffixed and date-only values pass through).
+ * For a pre-1970 naive value with known coordinates, the conversion is done
+ * by the API's `/timezone/offset` `datetime_local` mode so the historical
+ * correction overlay applies. Everything else — including every post-1970
+ * conversion — stays on the local, zero-latency Intl path.
+ */
+export declare function localToUtcIsoHistorical(field: string, dt: string, tz?: string, coords?: BirthCoords, timezoneField?: string): Promise<string>;

package/dist/tools/datetime-historical.js

@@ -0,0 +1,77 @@
+/**
+ * Historically-correct local → UTC conversion.
+ *
+ * IANA tzdata — Node's Intl and the Go engine's tzdata alike — is only
+ * authoritative from 1970. Before the US Uniform Time Act (effective 1967),
+ * DST was a state and municipal matter, and tzdata models each zone's
+ * reference city only. `localToUtcIso`'s Intl math is therefore silently an
+ * hour off for births like Robbinsdale, MN 1961-10-09 17:56 (Minnesota was on
+ * CST while America/Chicago says CDT), which flips the Ascendant sign and the
+ * HD design-Moon gate.
+ *
+ * The Go API owns the correction: `POST /timezone/offset` with
+ * `datetime_local` + coordinates resolves through its historical-correction
+ * overlay (apps/api/go-sidecar/internal/historicaltz) and returns the true
+ * instant plus a `tz_confidence` grade. This module routes the conversions
+ * that need it — pre-1970, naive, with known coordinates — through that
+ * endpoint, and leaves every other case on the local Intl path, which is
+ * exactly as authoritative as the server for 1970+.
+ *
+ * Fallback discipline: if the server call fails or resolves a different zone
+ * than the caller explicitly named, we fall back to `localToUtcIso` — the
+ * pre-existing behavior — rather than failing the chart call. Best effort
+ * beats an outage; the server remains the single authority whenever it is
+ * reachable.
+ */
+import { getActiveClient } from "../backend/client.js";
+import { hasZoneSuffix, isNaiveClockTime, localToUtcIso } from "./datetime.js";
+/** Where IANA tzdata stops being reference-city best effort. */
+export const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
+/** True when a naive local datetime needs the server-side historical path. */
+export function needsHistoricalResolution(dt, coords) {
+    const value = (dt ?? "").trim();
+    if (!isNaiveClockTime(value) || hasZoneSuffix(value))
+        return false;
+    const year = Number(value.slice(0, 4));
+    return (Number.isFinite(year) &&
+        year < TZDATA_AUTHORITATIVE_FROM_YEAR &&
+        typeof coords?.latitude === "number" &&
+        typeof coords?.longitude === "number");
+}
+/**
+ * `localToUtcIso`, but historically correct when it matters.
+ *
+ * Same contract as `localToUtcIso` (naive value with no `tz` throws the
+ * ambiguous-datetime error; zone-suffixed and date-only values pass through).
+ * For a pre-1970 naive value with known coordinates, the conversion is done
+ * by the API's `/timezone/offset` `datetime_local` mode so the historical
+ * correction overlay applies. Everything else — including every post-1970
+ * conversion — stays on the local, zero-latency Intl path.
+ */
+export async function localToUtcIsoHistorical(field, dt, tz, coords, timezoneField = "timezone") {
+    const value = (dt ?? "").trim();
+    if (!needsHistoricalResolution(value, coords) || !tz || tz.trim() === "") {
+        // Includes the naive-without-tz case, which must throw the same
+        // ambiguous-datetime error localToUtcIso throws.
+        return localToUtcIso(field, dt, tz, timezoneField);
+    }
+    try {
+        const res = (await getActiveClient().request("POST", "/timezone/offset", {
+            data: {
+                lat: coords.latitude,
+                lon: coords.longitude,
+                datetime_local: value,
+            },
+        }));
+        // Respect an explicit caller zone: the server resolves the zone from
+        // the coordinates, so only trust its instant when the zones agree.
+        if (res?.resolved_utc && (!res.timezone || res.timezone === tz.trim())) {
+            return res.resolved_utc;
+        }
+    }
+    catch {
+        // Server unreachable or rejected the request — fall through to the
+        // local conversion rather than failing the chart call.
+    }
+    return localToUtcIso(field, dt, tz, timezoneField);
+}

package/dist/tools/specialized/acg.js

@@ -1,7 +1,8 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
     "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
     "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
@@ -67,7 +68,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
+            epoch: await localToUtcIsoHistorical("birth_datetime", args.birth_datetime, args.timezone, { latitude: args.birth_latitude, longitude: args.birth_longitude }),
         };
         if (args.bodies)
             body.bodies = args.bodies;
@@ -164,7 +165,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
+            epoch: await localToUtcIsoHistorical("birth_datetime", args.birth_datetime, args.timezone, { latitude: args.birth_latitude, longitude: args.birth_longitude }),
             query_lat: args.query_latitude,
             query_lon: args.query_longitude,
         };

package/dist/tools/specialized/eclipse.js

@@ -60,12 +60,14 @@ registerTool({
             return await getActiveClient().request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
         }
         else {
-            // Global query — route to global endpoint
-            const params = {};
+            // Global query — forward-search for the next eclipse of this type,
+            // anywhere on Earth. /eclipse/solar|lunar/global classify whatever
+            // eclipse (if any) is occurring exactly at a given date, so they
+            // can't answer "when is the next one" — /eclipse/next can.
+            const params = { eclipse_type: args.eclipse_type ?? "any" };
             if (args.after_date)
                 params.date = args.after_date;
-            const endpoint = args.eclipse_type === "lunar" ? "/eclipse/lunar/global" : "/eclipse/solar/global";
-            return await getActiveClient().request("GET", endpoint, { params, timeoutMs: 60_000 });
+            return await getActiveClient().request("GET", "/eclipse/next", { params, timeoutMs: 60_000 });
         }
     },
 });