ether-to-astro 1.2.0 → 1.3.0

package/dist/astro-service/natal-service.js

@@ -0,0 +1,179 @@
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import { PLANETS, ZODIAC_SIGNS } from '../types.js';
+import { resolveHouseSystem } from './shared.js';
+/**
+ * Internal natal/chart-state workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns natal chart initialization, house resolution, and basic
+ * server-status serialization while the public `AstroService` facade preserves
+ * the existing contract for MCP and CLI callers.
+ */
+export class NatalService {
+    ephem;
+    houseCalc;
+    mcpStartupDefaults;
+    isInitialized;
+    constructor(deps) {
+        this.ephem = deps.ephem;
+        this.houseCalc = deps.houseCalc;
+        this.mcpStartupDefaults = deps.mcpStartupDefaults;
+        this.isInitialized = deps.isInitialized;
+    }
+    /**
+     * Build and cache the shared natal chart payload used by later workflows.
+     */
+    setNatalChart(input) {
+        const requestedHouseSystem = input.house_system ?? null;
+        const chart = {
+            name: input.name,
+            birthDate: {
+                year: input.year,
+                month: input.month,
+                day: input.day,
+                hour: input.hour,
+                minute: input.minute,
+            },
+            location: {
+                latitude: input.latitude,
+                longitude: input.longitude,
+                timezone: input.timezone,
+            },
+        };
+        const birthTimeDisambiguation = input.birth_time_disambiguation ?? 'reject';
+        const utcDate = localToUTC(chart.birthDate, chart.location.timezone, birthTimeDisambiguation);
+        const utcComponents = utcToLocal(utcDate, 'UTC');
+        const jd = this.ephem.dateToJulianDay(utcDate);
+        const planetIds = Object.values(PLANETS);
+        const positions = this.ephem.getAllPlanets(jd, planetIds);
+        const isPolar = Math.abs(chart.location.latitude) > 66;
+        let houseSystem = requestedHouseSystem || 'P';
+        if (isPolar && houseSystem === 'P') {
+            houseSystem = 'W';
+        }
+        const houses = this.houseCalc.calculateHouses(jd, chart.location.latitude, chart.location.longitude, houseSystem);
+        const storedChart = {
+            ...chart,
+            planets: positions,
+            julianDay: jd,
+            houseSystem: houses.system,
+            requestedHouseSystem: requestedHouseSystem ?? undefined,
+            utcDateTime: utcComponents,
+        };
+        const sun = positions.find((position) => position.planet === 'Sun');
+        const moon = positions.find((position) => position.planet === 'Moon');
+        if (!sun || !moon) {
+            throw new Error('Ephemeris failed to compute Sun/Moon positions for natal chart.');
+        }
+        const formatDegree = (longitude) => {
+            const sign = ZODIAC_SIGNS[Math.floor(longitude / 30)];
+            const degree = longitude % 30;
+            return `${degree.toFixed(0)}° ${sign}`;
+        };
+        const localTimeStr = `${chart.birthDate.month}/${chart.birthDate.day}/${chart.birthDate.year} ${chart.birthDate.hour}:${String(chart.birthDate.minute).padStart(2, '0')}`;
+        const utcTimeStr = `${utcComponents.month}/${utcComponents.day}/${utcComponents.year} ${utcComponents.hour}:${String(utcComponents.minute).padStart(2, '0')} UTC`;
+        const systemNames = {
+            P: 'Placidus',
+            W: 'Whole Sign',
+            K: 'Koch',
+            E: 'Equal',
+        };
+        const latDir = chart.location.latitude >= 0 ? 'N' : 'S';
+        const lonDir = chart.location.longitude >= 0 ? 'E' : 'W';
+        const latAbs = Math.abs(chart.location.latitude);
+        const lonAbs = Math.abs(chart.location.longitude);
+        const feedback = [
+            `Natal chart saved for ${chart.name}`,
+            '',
+            'Birth Details:',
+            `- Local Time: ${localTimeStr} (${chart.location.timezone})`,
+            `- UTC Time: ${utcTimeStr}`,
+            `- Location: ${latAbs.toFixed(2)}°${latDir}, ${lonAbs.toFixed(2)}°${lonDir}`,
+            '',
+            'Chart Angles:',
+            `- Sun: ${formatDegree(sun.longitude)}`,
+            `- Moon: ${formatDegree(moon.longitude)}`,
+            `- Ascendant: ${formatDegree(houses.ascendant)}`,
+            `- MC: ${formatDegree(houses.mc)}`,
+            '',
+            `House System: ${systemNames[houses.system] || houses.system}`,
+        ];
+        if (isPolar && houses.system !== houseSystem) {
+            feedback.push('', `Note: Polar latitude detected (${chart.location.latitude.toFixed(1)}°). Requested ${systemNames[houseSystem]}, using ${systemNames[houses.system]} instead.`);
+        }
+        else if (isPolar) {
+            feedback.push('', `Note: Polar latitude detected (${chart.location.latitude.toFixed(1)}°). Using ${systemNames[houses.system]} house system.`);
+        }
+        const structuredData = {
+            name: chart.name,
+            birthTime: {
+                local: localTimeStr,
+                utc: utcTimeStr,
+                timezone: chart.location.timezone,
+            },
+            location: {
+                latitude: chart.location.latitude,
+                longitude: chart.location.longitude,
+            },
+            julianDay: jd,
+            requestedHouseSystem,
+            resolvedHouseSystem: houses.system,
+            angles: {
+                sun: formatDegree(sun.longitude),
+                moon: formatDegree(moon.longitude),
+                ascendant: formatDegree(houses.ascendant),
+                mc: formatDegree(houses.mc),
+            },
+            isPolar,
+        };
+        return {
+            chart: storedChart,
+            data: structuredData,
+            text: feedback.join('\n'),
+        };
+    }
+    /**
+     * Calculate house cusps and angles for a natal chart.
+     */
+    getHouses(natalChart, input = {}) {
+        const system = resolveHouseSystem(natalChart, this.mcpStartupDefaults, input.system);
+        if (!natalChart.julianDay) {
+            throw new Error('Natal chart is missing julianDay. Re-run set_natal_chart to fix.');
+        }
+        const houses = this.houseCalc.calculateHouses(natalChart.julianDay, natalChart.location.latitude, natalChart.location.longitude, system);
+        const humanLines = houses.cusps
+            .slice(1)
+            .map((degree, index) => {
+            const sign = ZODIAC_SIGNS[Math.floor(degree / 30)];
+            return `House ${index + 1}: ${(degree % 30).toFixed(2)}° ${sign}`;
+        })
+            .join('\n');
+        const humanText = `Houses (${houses.system}):\nAsc: ${houses.ascendant.toFixed(2)}° | MC: ${houses.mc.toFixed(2)}°\n\n${humanLines}`;
+        return {
+            data: houses,
+            text: humanText,
+        };
+    }
+    /**
+     * Summarize process-local server state and configured startup defaults.
+     */
+    getServerStatus(natalChart) {
+        const statusData = {
+            serverVersion: '1.0.0',
+            hasNatalChart: natalChart !== null,
+            natalChartName: natalChart?.name ?? null,
+            natalChartTimezone: natalChart?.location.timezone ?? null,
+            startupDefaults: {
+                preferredTimezone: this.mcpStartupDefaults.preferredTimezone ?? null,
+                preferredHouseStyle: this.mcpStartupDefaults.preferredHouseStyle ?? null,
+                weekdayLabels: this.mcpStartupDefaults.weekdayLabels ?? null,
+            },
+            ephemerisInitialized: this.isInitialized(),
+            stateModel: 'stateful-per-process',
+        };
+        const humanText = natalChart
+            ? `Server ready. Natal chart loaded: ${natalChart.name} (${natalChart.location.timezone})`
+            : 'Server ready. No natal chart loaded — call set_natal_chart first.';
+        return { data: statusData, text: humanText };
+    }
+}

package/dist/astro-service/rising-sign-service.d.ts

@@ -0,0 +1,37 @@
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import type { GetRisingSignWindowsInput, ServiceResult } from './service-types.js';
+interface RisingSignServiceDependencies {
+    ephem: EphemerisCalculator;
+    houseCalc: HouseCalculator;
+}
+/**
+ * Internal rising-sign window scanner used by `AstroService`.
+ *
+ * @remarks
+ * This module owns the local-day scan, optional exact-boundary refinement, and
+ * serialization of sign windows while the public facade keeps the same method
+ * signature and result shape.
+ */
+export declare class RisingSignService {
+    private readonly ephem;
+    private readonly houseCalc;
+    constructor(deps: RisingSignServiceDependencies);
+    /**
+     * Find rising-sign windows across a local calendar day.
+     */
+    getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Sample the ascendant sign for a specific moment.
+     */
+    private getAscSign;
+    /**
+     * Binary-search a sign change down to a stable exact-mode boundary.
+     */
+    private refineBoundary;
+    /**
+     * Probe a scan bucket and emit every sign transition inside it.
+     */
+    private findSignTransitionsInBucket;
+}
+export {};

package/dist/astro-service/rising-sign-service.js

@@ -0,0 +1,137 @@
+import { formatInTimezone } from '../formatter.js';
+import { addLocalDays, formatLocalTimestampWithOffset, localToUTC, utcToLocal, } from '../time-utils.js';
+import { ZODIAC_SIGNS } from '../types.js';
+import { parseDateOnlyInput } from './date-input.js';
+import { normalizeLongitude } from './shared.js';
+/**
+ * Internal rising-sign window scanner used by `AstroService`.
+ *
+ * @remarks
+ * This module owns the local-day scan, optional exact-boundary refinement, and
+ * serialization of sign windows while the public facade keeps the same method
+ * signature and result shape.
+ */
+export class RisingSignService {
+    ephem;
+    houseCalc;
+    constructor(deps) {
+        this.ephem = deps.ephem;
+        this.houseCalc = deps.houseCalc;
+    }
+    /**
+     * Find rising-sign windows across a local calendar day.
+     */
+    getRisingSignWindows(input) {
+        const mode = input.mode ?? 'approximate';
+        if (mode !== 'approximate' && mode !== 'exact') {
+            throw new Error(`Invalid mode: ${mode} (must be approximate or exact)`);
+        }
+        if (input.latitude < -90 || input.latitude > 90) {
+            throw new Error(`Invalid latitude: ${input.latitude} (must be between -90 and 90)`);
+        }
+        if (input.longitude < -180 || input.longitude > 180) {
+            throw new Error(`Invalid longitude: ${input.longitude} (must be between -180 and 180)`);
+        }
+        const parsed = parseDateOnlyInput(input.date);
+        try {
+            utcToLocal(new Date(), input.timezone);
+        }
+        catch {
+            throw new Error(`Invalid timezone: ${input.timezone}`);
+        }
+        const dayStartLocal = {
+            year: parsed.year,
+            month: parsed.month,
+            day: parsed.day,
+            hour: 0,
+            minute: 0,
+            second: 0,
+        };
+        const dayStartUtc = localToUTC(dayStartLocal, input.timezone);
+        const dayEndUtc = addLocalDays(dayStartLocal, input.timezone, 1);
+        const stepMs = mode === 'exact' ? 60 * 60 * 1000 : 2 * 60 * 60 * 1000;
+        const probeStepMs = mode === 'exact' ? 5 * 60 * 1000 : 30 * 60 * 1000;
+        const boundaries = [dayStartUtc];
+        let cursor = dayStartUtc;
+        while (cursor < dayEndUtc) {
+            const next = new Date(Math.min(cursor.getTime() + stepMs, dayEndUtc.getTime()));
+            boundaries.push(...this.findSignTransitionsInBucket(input, mode, cursor, next, probeStepMs));
+            cursor = next;
+        }
+        boundaries.push(dayEndUtc);
+        const windows = boundaries.slice(0, -1).map((start, index) => {
+            const end = boundaries[index + 1];
+            const sample = new Date((start.getTime() + end.getTime()) / 2);
+            const sign = this.getAscSign(input, sample).sign;
+            return {
+                sign,
+                start: formatLocalTimestampWithOffset(start, input.timezone),
+                end: formatLocalTimestampWithOffset(end, input.timezone),
+                durationMs: end.getTime() - start.getTime(),
+            };
+        });
+        const structuredData = {
+            date: input.date,
+            timezone: input.timezone,
+            location: {
+                latitude: input.latitude,
+                longitude: input.longitude,
+            },
+            mode,
+            windows,
+        };
+        const humanText = `Rising Sign Windows (${input.date}, ${input.timezone}, ${mode}):\n\n${windows
+            .map((window) => `${window.sign}: ${formatInTimezone(new Date(window.start), input.timezone)} → ${formatInTimezone(new Date(window.end), input.timezone)}`)
+            .join('\n')}`;
+        return {
+            data: structuredData,
+            text: humanText,
+        };
+    }
+    /**
+     * Sample the ascendant sign for a specific moment.
+     */
+    getAscSign(input, date) {
+        const jd = this.ephem.dateToJulianDay(date);
+        const houses = this.houseCalc.calculateHouses(jd, input.latitude, input.longitude, 'P');
+        const normalized = normalizeLongitude(houses.ascendant);
+        return { sign: ZODIAC_SIGNS[Math.floor(normalized / 30)], longitude: normalized };
+    }
+    /**
+     * Binary-search a sign change down to a stable exact-mode boundary.
+     */
+    refineBoundary(input, left, right) {
+        const leftSign = this.getAscSign(input, left).sign;
+        let lo = left;
+        let hi = right;
+        for (let i = 0; i < 25; i++) {
+            const mid = new Date((lo.getTime() + hi.getTime()) / 2);
+            const midSign = this.getAscSign(input, mid).sign;
+            if (midSign === leftSign) {
+                lo = mid;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        return hi;
+    }
+    /**
+     * Probe a scan bucket and emit every sign transition inside it.
+     */
+    findSignTransitionsInBucket(input, mode, start, end, probeStepMs) {
+        const boundaries = [];
+        let probeCursor = start;
+        let currentSign = this.getAscSign(input, probeCursor).sign;
+        while (probeCursor < end) {
+            const probeNext = new Date(Math.min(probeCursor.getTime() + probeStepMs, end.getTime()));
+            const nextSign = this.getAscSign(input, probeNext).sign;
+            if (nextSign !== currentSign) {
+                boundaries.push(mode === 'exact' ? this.refineBoundary(input, probeCursor, probeNext) : probeNext);
+            }
+            probeCursor = probeNext;
+            currentSign = nextSign;
+        }
+        return boundaries;
+    }
+}

package/dist/astro-service/service-types.d.ts

@@ -0,0 +1,82 @@
+import type { Disambiguation } from '../time-utils.js';
+import type { ElectionalHouseSystem, HouseSystem } from '../types.js';
+/**
+ * Public input type for building and caching the shared natal chart payload.
+ */
+export interface SetNatalChartInput {
+    name: string;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    house_system?: HouseSystem;
+    birth_time_disambiguation?: Disambiguation;
+}
+/**
+ * Public input type for querying natal transits.
+ */
+export interface GetTransitsInput {
+    date?: string;
+    categories?: string[];
+    include_mundane?: boolean;
+    days_ahead?: number;
+    mode?: 'snapshot' | 'best_hit' | 'forecast';
+    max_orb?: number;
+    exact_only?: boolean;
+    applying_only?: boolean;
+}
+/**
+ * Public input type for stateless electional context lookup.
+ */
+export interface GetElectionalContextInput {
+    date: string;
+    time: string;
+    timezone: string;
+    latitude: number;
+    longitude: number;
+    house_system?: ElectionalHouseSystem;
+    include_ruler_basics?: boolean;
+    include_planetary_applications?: boolean;
+    orb_degrees?: number;
+}
+/**
+ * Public input type for house lookup on an existing natal chart.
+ */
+export interface GetHousesInput {
+    system?: string;
+}
+/**
+ * Public input type for daily rising-sign window lookup.
+ */
+export interface GetRisingSignWindowsInput {
+    date: string;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    mode?: 'approximate' | 'exact';
+}
+/**
+ * Public output-wrapper shared by service methods that return data plus text.
+ */
+export interface ServiceResult<T> {
+    data: T;
+    text: string;
+}
+/**
+ * Public input type for chart rendering methods.
+ */
+export interface GenerateChartInput {
+    theme?: 'light' | 'dark';
+    format?: 'svg' | 'png' | 'webp';
+    output_path?: string;
+}
+/**
+ * Public input type for transit-chart rendering methods.
+ */
+export interface GenerateTransitChartInput extends GenerateChartInput {
+    date?: string;
+}

package/dist/astro-service/service-types.js

@@ -0,0 +1 @@
+export {};

package/dist/astro-service/shared.d.ts

@@ -0,0 +1,65 @@
+import type { McpStartupDefaults } from '../entrypoint.js';
+import { type HouseData, type HouseSystem, type NatalChart } from '../types.js';
+/**
+ * Normalize any longitude into the standard 0-360 range.
+ *
+ * @param longitude - Raw longitude in degrees, including negative or >360 values
+ * @returns Longitude normalized into the half-open interval [0, 360)
+ */
+export declare function normalizeLongitude(longitude: number): number;
+/**
+ * Convert a raw longitude into zodiac sign and in-sign degree.
+ *
+ * @param longitude - Raw longitude in degrees
+ * @returns Sign name plus degree within that sign
+ *
+ * @remarks
+ * Rounded degree values that would otherwise land on 30.00 are carried into
+ * the next sign so serialized placement stays astrologically valid.
+ */
+export declare function getSignAndDegree(longitude: number): {
+    sign: string;
+    degree: number;
+};
+/**
+ * Map a longitude to its house number for a resolved house table.
+ *
+ * @param longitude - Longitude to place into a house
+ * @param houses - Resolved house cusps for the relevant chart or moment
+ * @returns 1-based house number
+ */
+export declare function getHouseNumber(longitude: number, houses: HouseData): number;
+/**
+ * Resolve the house system precedence shared by service entrypoints.
+ *
+ * @param natalChart - Natal chart carrying stored and requested house system state
+ * @param startupDefaults - Process startup defaults that can provide fallback policy
+ * @param explicitSystem - Per-call override when the caller requested a specific system
+ * @returns Final house system to use for the calculation
+ */
+export declare function resolveHouseSystem(natalChart: NatalChart, startupDefaults: Readonly<McpStartupDefaults>, explicitSystem?: string): HouseSystem;
+/**
+ * Resolve the reporting timezone precedence shared by service entrypoints.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used as fallback
+ * @returns Final reporting timezone for text and date labels
+ */
+export declare function resolveReportingTimezone(startupDefaults: Readonly<McpStartupDefaults>, explicitTimezone?: string, natalTimezone?: string): string;
+/**
+ * Resolve both calculation and reporting timezones for chart-based workflows.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitReportingTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used for local-day interpretation
+ * @returns Calculation timezone plus reporting timezone
+ *
+ * @remarks
+ * Calculation timezone controls local-day math and ephemeris lookups. Reporting
+ * timezone controls user-facing labels and formatted timestamps.
+ */
+export declare function resolveTimezones(startupDefaults: Readonly<McpStartupDefaults>, explicitReportingTimezone?: string, natalTimezone?: string): {
+    calculationTimezone: string;
+    reportingTimezone: string;
+};

package/dist/astro-service/shared.js

@@ -0,0 +1,98 @@
+import { ZODIAC_SIGNS } from '../types.js';
+/**
+ * Normalize any longitude into the standard 0-360 range.
+ *
+ * @param longitude - Raw longitude in degrees, including negative or >360 values
+ * @returns Longitude normalized into the half-open interval [0, 360)
+ */
+export function normalizeLongitude(longitude) {
+    return ((longitude % 360) + 360) % 360;
+}
+/**
+ * Convert a raw longitude into zodiac sign and in-sign degree.
+ *
+ * @param longitude - Raw longitude in degrees
+ * @returns Sign name plus degree within that sign
+ *
+ * @remarks
+ * Rounded degree values that would otherwise land on 30.00 are carried into
+ * the next sign so serialized placement stays astrologically valid.
+ */
+export function getSignAndDegree(longitude) {
+    const normalized = normalizeLongitude(longitude);
+    const baseSignIndex = Math.floor(normalized / 30);
+    const roundedDegree = Number.parseFloat((normalized % 30).toFixed(2));
+    const shouldCarryToNextSign = roundedDegree >= 30;
+    const signIndex = shouldCarryToNextSign
+        ? (baseSignIndex + 1) % ZODIAC_SIGNS.length
+        : baseSignIndex;
+    return {
+        sign: ZODIAC_SIGNS[signIndex],
+        degree: shouldCarryToNextSign ? 0 : roundedDegree,
+    };
+}
+/**
+ * Map a longitude to its house number for a resolved house table.
+ *
+ * @param longitude - Longitude to place into a house
+ * @param houses - Resolved house cusps for the relevant chart or moment
+ * @returns 1-based house number
+ */
+export function getHouseNumber(longitude, houses) {
+    const normalized = normalizeLongitude(longitude);
+    for (let house = 1; house <= 12; house++) {
+        const start = normalizeLongitude(houses.cusps[house]);
+        const nextHouse = house === 12 ? 1 : house + 1;
+        const end = normalizeLongitude(houses.cusps[nextHouse]);
+        const span = (end - start + 360) % 360;
+        const offset = (normalized - start + 360) % 360;
+        if (span === 0 || offset === 0 || offset < span) {
+            return house;
+        }
+    }
+    return 12;
+}
+/**
+ * Resolve the house system precedence shared by service entrypoints.
+ *
+ * @param natalChart - Natal chart carrying stored and requested house system state
+ * @param startupDefaults - Process startup defaults that can provide fallback policy
+ * @param explicitSystem - Per-call override when the caller requested a specific system
+ * @returns Final house system to use for the calculation
+ */
+export function resolveHouseSystem(natalChart, startupDefaults, explicitSystem) {
+    return (explicitSystem ||
+        natalChart.requestedHouseSystem ||
+        startupDefaults.preferredHouseStyle ||
+        natalChart.houseSystem ||
+        'P');
+}
+/**
+ * Resolve the reporting timezone precedence shared by service entrypoints.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used as fallback
+ * @returns Final reporting timezone for text and date labels
+ */
+export function resolveReportingTimezone(startupDefaults, explicitTimezone, natalTimezone) {
+    return explicitTimezone ?? startupDefaults.preferredTimezone ?? natalTimezone ?? 'UTC';
+}
+/**
+ * Resolve both calculation and reporting timezones for chart-based workflows.
+ *
+ * @param startupDefaults - Process startup defaults
+ * @param explicitReportingTimezone - Per-call reporting timezone override
+ * @param natalTimezone - Natal chart timezone used for local-day interpretation
+ * @returns Calculation timezone plus reporting timezone
+ *
+ * @remarks
+ * Calculation timezone controls local-day math and ephemeris lookups. Reporting
+ * timezone controls user-facing labels and formatted timestamps.
+ */
+export function resolveTimezones(startupDefaults, explicitReportingTimezone, natalTimezone) {
+    return {
+        calculationTimezone: natalTimezone ?? 'UTC',
+        reportingTimezone: resolveReportingTimezone(startupDefaults, explicitReportingTimezone, natalTimezone),
+    };
+}

package/dist/astro-service/sky-service.d.ts

@@ -0,0 +1,48 @@
+import type { EclipseCalculator } from '../eclipses.js';
+import type { McpStartupDefaults } from '../entrypoint.js';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { RiseSetCalculator } from '../riseset.js';
+import { type NatalChart } from '../types.js';
+import type { ServiceResult } from './service-types.js';
+interface SkyServiceDependencies {
+    ephem: EphemerisCalculator;
+    riseSetCalc: RiseSetCalculator;
+    eclipseCalc: EclipseCalculator;
+    mcpStartupDefaults: Readonly<McpStartupDefaults>;
+    now: () => Date;
+    formatTimestamp: (date: Date, timezone: string) => string;
+}
+/**
+ * Internal current-sky and runtime lookup workflow used by `AstroService`.
+ *
+ * @remarks
+ * This module owns read-only runtime lookups that depend on "now", including
+ * retrogrades, asteroid/node snapshots, rise/set tables, and eclipse queries.
+ */
+export declare class SkyService {
+    private readonly ephem;
+    private readonly riseSetCalc;
+    private readonly eclipseCalc;
+    private readonly mcpStartupDefaults;
+    private readonly now;
+    private readonly formatTimestamp;
+    constructor(deps: SkyServiceDependencies);
+    /**
+     * Return the currently retrograde planets for the requested reporting timezone.
+     */
+    getRetrogradePlanets(timezone?: string): ServiceResult<Record<string, unknown>>;
+    /**
+     * Return the next rise and set events after the local day anchor for the chart location.
+     */
+    getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>>;
+    /**
+     * Return current asteroid and node positions for the requested reporting timezone.
+     */
+    getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>>;
+    /**
+     * Look up the next solar and lunar eclipses after the current instant.
+     */
+    getNextEclipses(timezone?: string): ServiceResult<Record<string, unknown>>;
+    private getDateLabel;
+}
+export {};