ether-to-astro 1.2.0 → 1.3.0

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

@@ -0,0 +1,144 @@
+import { localToUTC, utcToLocal } from '../time-utils.js';
+import { ASTEROIDS, NODES, PLANETS } from '../types.js';
+import { resolveReportingTimezone } from './shared.js';
+/**
+ * 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 class SkyService {
+    ephem;
+    riseSetCalc;
+    eclipseCalc;
+    mcpStartupDefaults;
+    now;
+    formatTimestamp;
+    constructor(deps) {
+        this.ephem = deps.ephem;
+        this.riseSetCalc = deps.riseSetCalc;
+        this.eclipseCalc = deps.eclipseCalc;
+        this.mcpStartupDefaults = deps.mcpStartupDefaults;
+        this.now = deps.now;
+        this.formatTimestamp = deps.formatTimestamp;
+    }
+    /**
+     * Return the currently retrograde planets for the requested reporting timezone.
+     */
+    getRetrogradePlanets(timezone) {
+        const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+        const now = this.now();
+        const jd = this.ephem.dateToJulianDay(now);
+        const positions = this.ephem.getAllPlanets(jd, Object.values(PLANETS));
+        const retrograde = positions.filter((position) => position.isRetrograde);
+        const structuredData = {
+            date: this.getDateLabel(now, resolvedTimezone),
+            timezone: resolvedTimezone,
+            planets: retrograde,
+        };
+        const humanText = retrograde.length === 0
+            ? 'No planets are currently retrograde.'
+            : `Retrograde Planets:\n\n${retrograde.map((position) => `${position.planet}: ${position.degree.toFixed(2)}° ${position.sign}`).join('\n')}`;
+        return { data: structuredData, text: humanText };
+    }
+    /**
+     * Return the next rise and set events after the local day anchor for the chart location.
+     */
+    async getRiseSetTimes(natalChart) {
+        const timezone = natalChart.location.timezone;
+        const reportingTimezone = this.mcpStartupDefaults.preferredTimezone || timezone;
+        const now = this.now();
+        const localNow = utcToLocal(now, timezone);
+        const localMidnight = {
+            year: localNow.year,
+            month: localNow.month,
+            day: localNow.day,
+            hour: 0,
+            minute: 0,
+            second: 0,
+        };
+        const midnightUTC = localToUTC(localMidnight, timezone);
+        const results = await this.riseSetCalc.getAllRiseSet(midnightUTC, natalChart.location.latitude, natalChart.location.longitude);
+        const structuredData = {
+            date: this.getDateLabel(now, timezone),
+            timezone,
+            times: results.map((result) => ({
+                planet: result.planet,
+                rise: result.rise?.toISOString() ?? null,
+                set: result.set?.toISOString() ?? null,
+            })),
+        };
+        const humanText = `Rise/Set Times:\n\n${results
+            .map((result) => {
+            const rise = result.rise ? this.formatTimestamp(result.rise, reportingTimezone) : 'none';
+            const set = result.set ? this.formatTimestamp(result.set, reportingTimezone) : 'none';
+            return `${result.planet}: Rise ${rise}, Set ${set}`;
+        })
+            .join('\n')}`;
+        return {
+            data: structuredData,
+            text: humanText,
+        };
+    }
+    /**
+     * Return current asteroid and node positions for the requested reporting timezone.
+     */
+    getAsteroidPositions(timezone) {
+        const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+        const now = this.now();
+        const jd = this.ephem.dateToJulianDay(now);
+        const positions = this.ephem.getAllPlanets(jd, [...ASTEROIDS, ...NODES]);
+        const structuredData = {
+            date: this.getDateLabel(now, resolvedTimezone),
+            timezone: resolvedTimezone,
+            positions,
+        };
+        const humanText = `Asteroid & Node Positions:\n\n${positions
+            .map((position) => {
+            const retrogradeLabel = position.isRetrograde ? ' Rx' : '';
+            return `${position.planet}: ${position.degree.toFixed(2)}° ${position.sign}${retrogradeLabel}`;
+        })
+            .join('\n')}`;
+        return {
+            data: structuredData,
+            text: humanText,
+        };
+    }
+    /**
+     * Look up the next solar and lunar eclipses after the current instant.
+     */
+    getNextEclipses(timezone) {
+        const resolvedTimezone = resolveReportingTimezone(this.mcpStartupDefaults, timezone);
+        const jd = this.ephem.dateToJulianDay(this.now());
+        const solarEclipse = this.eclipseCalc.findNextSolarEclipse(jd);
+        const lunarEclipse = this.eclipseCalc.findNextLunarEclipse(jd);
+        const eclipses = [];
+        const humanLines = [];
+        if (solarEclipse) {
+            eclipses.push({
+                type: solarEclipse.type,
+                eclipseType: solarEclipse.eclipseType,
+                maxTime: solarEclipse.maxTime.toISOString(),
+            });
+            humanLines.push(`Next Solar Eclipse: ${this.formatTimestamp(solarEclipse.maxTime, resolvedTimezone)} (${solarEclipse.eclipseType})`);
+        }
+        if (lunarEclipse) {
+            eclipses.push({
+                type: lunarEclipse.type,
+                eclipseType: lunarEclipse.eclipseType,
+                maxTime: lunarEclipse.maxTime.toISOString(),
+            });
+            humanLines.push(`Next Lunar Eclipse: ${this.formatTimestamp(lunarEclipse.maxTime, resolvedTimezone)} (${lunarEclipse.eclipseType})`);
+        }
+        const structuredData = { timezone: resolvedTimezone, eclipses };
+        const humanText = eclipses.length === 0
+            ? 'No eclipses found in the near future.'
+            : `Upcoming Eclipses:\n\n${humanLines.join('\n')}`;
+        return { data: structuredData, text: humanText };
+    }
+    getDateLabel(date, timezone) {
+        const localDate = utcToLocal(date, timezone);
+        return `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
+    }
+}

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

@@ -0,0 +1,82 @@
+import type { McpStartupDefaults } from '../entrypoint.js';
+import type { EphemerisCalculator } from '../ephemeris.js';
+import type { HouseCalculator } from '../houses.js';
+import { type TransitCalculator } from '../transits.js';
+import { type NatalChart } from '../types.js';
+import type { GetTransitsInput, ServiceResult } from './service-types.js';
+/**
+ * Dependencies needed by the extracted transit workflow.
+ */
+interface TransitServiceDependencies {
+    ephem: EphemerisCalculator;
+    transitCalc: TransitCalculator;
+    houseCalc: HouseCalculator;
+    mcpStartupDefaults: Readonly<McpStartupDefaults>;
+    now: () => Date;
+    formatTimestamp: (date: Date, timezone: string) => string;
+}
+/**
+ * Internal transit workflow service used by `AstroService`.
+ *
+ * @remarks
+ * This module owns transit-specific validation, aggregation, placement
+ * enrichment, mundane expansion, and human-readable response formatting while
+ * the public `AstroService` facade preserves the external contract.
+ */
+export declare class TransitService {
+    private readonly ephem;
+    private readonly transitCalc;
+    private readonly houseCalc;
+    private readonly mcpStartupDefaults;
+    private readonly now;
+    private readonly formatTimestamp;
+    constructor(deps: TransitServiceDependencies);
+    /**
+     * Build the transit payload and readable text for a natal chart query.
+     */
+    getTransits(natalChart: NatalChart, input?: GetTransitsInput): ServiceResult<Record<string, unknown>>;
+    /**
+     * Resolve the query anchor instant for a transit lookup.
+     *
+     * @param dateStr - Optional YYYY-MM-DD date supplied by the caller
+     * @param calculationTimezone - Timezone used for local-day interpretation
+     * @returns UTC instant representing local noon on the requested day
+     */
+    private resolveTargetDate;
+    /**
+     * Expand category filters into the concrete transiting planet ids to compute.
+     *
+     * @param categories - Requested category filters from the transit input
+     * @returns Deduplicated transiting planet ids in stable insertion order
+     */
+    private resolveTransitingPlanetIds;
+    /**
+     * Derive a simple supportive/challenging weather summary from mundane aspects.
+     *
+     * @param aspects - Mundane aspects for a single reporting day
+     * @returns Grouped weather identifiers keyed by tone
+     */
+    private getMundaneWeather;
+    /**
+     * Compute transit-to-transit mundane aspects for a single day's positions.
+     *
+     * @param date - Reporting date label used in stable aspect ids
+     * @param positions - Transiting planetary positions for the day
+     * @returns Sorted mundane aspects with orb and applying metadata
+     */
+    private getMundaneAspects;
+    /**
+     * Build the optional mundane payload for one transit day.
+     *
+     * @param dayUTC - UTC instant representing the day anchor
+     * @param timezone - Reporting timezone used for day labels
+     * @param transitingPlanetIds - Planet ids included in the mundane calculation
+     * @returns Daily mundane bundle with positions, aspects, and weather
+     */
+    private getMundaneDay;
+    /**
+     * Format a local date tuple into the service's canonical YYYY-MM-DD label.
+     */
+    private formatDateLabel;
+}
+export {};

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

@@ -0,0 +1,353 @@
+import { addLocalDays, localToUTC, utcToLocal } from '../time-utils.js';
+import { deduplicateTransits } from '../transits.js';
+import { ASPECTS, OUTER_PLANETS, PERSONAL_PLANETS, PLANET_NAMES, PLANETS, } from '../types.js';
+import { parseDateOnlyInput } from './date-input.js';
+import { getHouseNumber, getSignAndDegree, resolveHouseSystem, resolveTimezones, } from './shared.js';
+/**
+ * Internal transit workflow service used by `AstroService`.
+ *
+ * @remarks
+ * This module owns transit-specific validation, aggregation, placement
+ * enrichment, mundane expansion, and human-readable response formatting while
+ * the public `AstroService` facade preserves the external contract.
+ */
+export class TransitService {
+    ephem;
+    transitCalc;
+    houseCalc;
+    mcpStartupDefaults;
+    now;
+    formatTimestamp;
+    constructor(deps) {
+        this.ephem = deps.ephem;
+        this.transitCalc = deps.transitCalc;
+        this.houseCalc = deps.houseCalc;
+        this.mcpStartupDefaults = deps.mcpStartupDefaults;
+        this.now = deps.now;
+        this.formatTimestamp = deps.formatTimestamp;
+    }
+    /**
+     * Build the transit payload and readable text for a natal chart query.
+     */
+    getTransits(natalChart, input = {}) {
+        const dateStr = input.date;
+        const categories = input.categories ?? ['all'];
+        const includeMundane = input.include_mundane ?? false;
+        const daysAhead = input.days_ahead ?? 0;
+        const requestedMode = input.mode;
+        const maxOrb = input.max_orb ?? 8;
+        const exactOnly = input.exact_only ?? false;
+        const applyingOnly = input.applying_only ?? false;
+        if (!Number.isFinite(daysAhead) || daysAhead < 0) {
+            throw new Error('days_ahead must be a finite number >= 0');
+        }
+        if (!Number.isFinite(maxOrb) || maxOrb < 0) {
+            throw new Error('max_orb must be a finite number >= 0');
+        }
+        if (requestedMode !== undefined &&
+            requestedMode !== 'snapshot' &&
+            requestedMode !== 'best_hit' &&
+            requestedMode !== 'forecast') {
+            throw new Error('mode must be one of: snapshot, best_hit, forecast');
+        }
+        if (!natalChart.julianDay) {
+            throw new Error('Natal chart is missing julianDay. Re-run set_natal_chart to fix.');
+        }
+        const mode = requestedMode ?? (daysAhead === 0 ? 'snapshot' : 'best_hit');
+        const modeSource = requestedMode === undefined ? 'legacy_default' : 'explicit';
+        const transitingPlanetIds = this.resolveTransitingPlanetIds(categories);
+        const { calculationTimezone, reportingTimezone } = resolveTimezones(this.mcpStartupDefaults, undefined, natalChart.location.timezone);
+        const targetDate = this.resolveTargetDate(dateStr, calculationTimezone);
+        const allTransits = [];
+        const transitsByDay = new Map();
+        const transitContext = new WeakMap();
+        const startLocal = utcToLocal(targetDate, calculationTimezone);
+        const effectiveDaysAhead = mode === 'snapshot' ? 0 : daysAhead;
+        for (let day = 0; day <= effectiveDaysAhead; day++) {
+            const dayUTC = addLocalDays(startLocal, calculationTimezone, day);
+            const julianDay = this.ephem.dateToJulianDay(dayUTC);
+            const transitingPlanets = this.ephem.getAllPlanets(julianDay, transitingPlanetIds);
+            const transits = this.transitCalc.findTransits(transitingPlanets, natalChart.planets || [], julianDay);
+            for (const transit of transits) {
+                transitContext.set(transit, { julianDay });
+            }
+            allTransits.push(...transits);
+            transitsByDay.set(this.formatDateLabel(utcToLocal(dayUTC, reportingTimezone)), transits);
+        }
+        const filterTransits = (transits) => {
+            let filtered = transits.filter((transit) => transit.orb <= maxOrb);
+            if (exactOnly) {
+                filtered = filtered.filter((transit) => transit.exactTime !== undefined);
+            }
+            if (applyingOnly) {
+                filtered = filtered.filter((transit) => transit.isApplying);
+            }
+            filtered.sort((left, right) => left.orb - right.orb);
+            return filtered;
+        };
+        const chartHouseSystem = resolveHouseSystem(natalChart, this.mcpStartupDefaults);
+        const natalHouses = this.houseCalc.calculateHouses(natalChart.julianDay, natalChart.location.latitude, natalChart.location.longitude, chartHouseSystem);
+        const transitHouseCache = new Map();
+        const planetIdsByName = new Map(Object.entries(PLANET_NAMES).map(([planetId, planetName]) => [planetName, Number(planetId)]));
+        const getTransitHouses = (julianDay) => {
+            const cached = transitHouseCache.get(julianDay);
+            if (cached) {
+                return cached;
+            }
+            const houses = this.houseCalc.calculateHouses(julianDay, natalChart.location.latitude, natalChart.location.longitude, chartHouseSystem);
+            transitHouseCache.set(julianDay, houses);
+            return houses;
+        };
+        const serializeTransit = (transit) => {
+            const transitPlacement = getSignAndDegree(transit.transitLongitude);
+            const natalPlacement = getSignAndDegree(transit.natalLongitude);
+            const context = transitContext.get(transit);
+            const transitHouseJulianDay = transit.exactTime
+                ? this.ephem.dateToJulianDay(transit.exactTime)
+                : (context?.julianDay ?? this.ephem.dateToJulianDay(targetDate));
+            const transitHouses = getTransitHouses(transitHouseJulianDay);
+            const exactTransitLongitude = transit.exactTime && planetIdsByName.has(transit.transitingPlanet)
+                ? this.ephem.getPlanetPosition(planetIdsByName.get(transit.transitingPlanet), transitHouseJulianDay).longitude
+                : transit.transitLongitude;
+            return {
+                transitingPlanet: transit.transitingPlanet,
+                aspect: transit.aspect,
+                natalPlanet: transit.natalPlanet,
+                orb: Number.parseFloat(transit.orb.toFixed(2)),
+                isApplying: transit.isApplying,
+                exactTimeStatus: transit.exactTimeStatus,
+                exactTime: transit.exactTime?.toISOString(),
+                transitLongitude: transit.transitLongitude,
+                natalLongitude: transit.natalLongitude,
+                transitSign: transitPlacement.sign,
+                transitDegree: transitPlacement.degree,
+                transitHouse: getHouseNumber(exactTransitLongitude, transitHouses),
+                natalSign: natalPlacement.sign,
+                natalDegree: natalPlacement.degree,
+                natalHouse: getHouseNumber(transit.natalLongitude, natalHouses),
+            };
+        };
+        const filteredTransits = filterTransits(deduplicateTransits(allTransits));
+        const dateLabel = this.formatDateLabel(utcToLocal(targetDate, reportingTimezone));
+        const windowEndLabel = this.formatDateLabel(utcToLocal(addLocalDays(startLocal, calculationTimezone, effectiveDaysAhead), reportingTimezone));
+        const structuredData = {
+            date: dateLabel,
+            timezone: reportingTimezone,
+            calculation_timezone: calculationTimezone,
+            reporting_timezone: reportingTimezone,
+            transits: filteredTransits.map(serializeTransit),
+        };
+        const metadata = {
+            mode,
+            mode_source: modeSource,
+            days_ahead: effectiveDaysAhead,
+            window_start: dateLabel,
+            window_end: windowEndLabel,
+        };
+        let responseData = structuredData;
+        let mundaneText = '';
+        if (mode === 'forecast') {
+            const forecastDays = Array.from(transitsByDay.entries())
+                .sort(([leftDate], [rightDate]) => leftDate.localeCompare(rightDate))
+                .map(([dayDate, dayTransits]) => ({
+                date: dayDate,
+                transits: filterTransits(deduplicateTransits(dayTransits)).map(serializeTransit),
+            }));
+            responseData = {
+                ...metadata,
+                timezone: reportingTimezone,
+                calculation_timezone: calculationTimezone,
+                reporting_timezone: reportingTimezone,
+                forecast: forecastDays,
+            };
+        }
+        else {
+            responseData = {
+                ...structuredData,
+                ...metadata,
+            };
+        }
+        if (includeMundane) {
+            const mundaneDays = [];
+            for (let day = 0; day <= daysAhead; day++) {
+                const dayUTC = addLocalDays(startLocal, calculationTimezone, day);
+                mundaneDays.push(this.getMundaneDay(dayUTC, reportingTimezone, transitingPlanetIds));
+            }
+            const [anchorMundane] = mundaneDays;
+            const mundaneData = {
+                date: anchorMundane.date,
+                timezone: anchorMundane.timezone,
+                positions: anchorMundane.positions,
+                aspects: anchorMundane.aspects,
+                days: mundaneDays,
+            };
+            responseData = { transits: responseData, mundane: mundaneData };
+            mundaneText = `\n\nCurrent Planetary Positions:\n\n${anchorMundane.positions
+                .map((position) => `${position.planet}: ${position.degree.toFixed(1)}° ${position.sign} (${position.isRetrograde ? 'Rx' : 'Direct'})`)
+                .join('\n')}`;
+            if (mode === 'forecast') {
+                mundaneText +=
+                    '\n\nNote: mundane positions remain anchored to the forecast start date in this mode.';
+            }
+        }
+        const formatHumanTransit = (transit) => {
+            const exactStr = transit.exactTime
+                ? ` - Exact: ${this.formatTimestamp(transit.exactTime, reportingTimezone)}`
+                : '';
+            const applyStr = transit.isApplying ? '(applying)' : '(separating)';
+            return `${transit.transitingPlanet} ${transit.aspect} ${transit.natalPlanet}: ${transit.orb.toFixed(2)}° orb ${applyStr}${exactStr}`;
+        };
+        const rangeStr = effectiveDaysAhead > 0 ? ` (next ${effectiveDaysAhead + 1} days)` : '';
+        let transitHeader;
+        if (mode === 'forecast') {
+            const forecastLines = Array.from(transitsByDay.entries())
+                .sort(([leftDate], [rightDate]) => leftDate.localeCompare(rightDate))
+                .map(([dayDate, dayTransits]) => {
+                const dedupedDay = filterTransits(deduplicateTransits(dayTransits));
+                const lines = dedupedDay.length === 0
+                    ? 'No transits found matching the specified criteria.'
+                    : dedupedDay.map(formatHumanTransit).join('\n');
+                return `${dayDate}:\n${lines}`;
+            })
+                .join('\n\n');
+            transitHeader = `Forecast transits${rangeStr}:\n\n${forecastLines}`;
+        }
+        else {
+            const humanLines = filteredTransits.map(formatHumanTransit).join('\n');
+            const modeLabel = mode === 'snapshot' ? 'Transit snapshot' : 'Best-hit transits';
+            transitHeader =
+                filteredTransits.length > 0
+                    ? `${modeLabel}${rangeStr}:\n\n${humanLines}`
+                    : 'No transits found matching the specified criteria.';
+        }
+        return {
+            data: responseData,
+            text: transitHeader + mundaneText,
+        };
+    }
+    /**
+     * Resolve the query anchor instant for a transit lookup.
+     *
+     * @param dateStr - Optional YYYY-MM-DD date supplied by the caller
+     * @param calculationTimezone - Timezone used for local-day interpretation
+     * @returns UTC instant representing local noon on the requested day
+     */
+    resolveTargetDate(dateStr, calculationTimezone) {
+        if (dateStr) {
+            const parsed = parseDateOnlyInput(dateStr);
+            return localToUTC(parsed, calculationTimezone);
+        }
+        const now = this.now();
+        const localNow = utcToLocal(now, calculationTimezone);
+        return localToUTC({ ...localNow, hour: 12, minute: 0, second: 0 }, calculationTimezone);
+    }
+    /**
+     * Expand category filters into the concrete transiting planet ids to compute.
+     *
+     * @param categories - Requested category filters from the transit input
+     * @returns Deduplicated transiting planet ids in stable insertion order
+     */
+    resolveTransitingPlanetIds(categories) {
+        const transitingPlanetIds = [];
+        if (categories.includes('all')) {
+            return Object.values(PLANETS);
+        }
+        if (categories.includes('moon')) {
+            transitingPlanetIds.push(PLANETS.MOON);
+        }
+        if (categories.includes('personal')) {
+            transitingPlanetIds.push(...PERSONAL_PLANETS.filter((planetId) => !transitingPlanetIds.includes(planetId)));
+        }
+        if (categories.includes('outer')) {
+            transitingPlanetIds.push(...OUTER_PLANETS.filter((planetId) => !transitingPlanetIds.includes(planetId)));
+        }
+        return transitingPlanetIds;
+    }
+    /**
+     * Derive a simple supportive/challenging weather summary from mundane aspects.
+     *
+     * @param aspects - Mundane aspects for a single reporting day
+     * @returns Grouped weather identifiers keyed by tone
+     */
+    getMundaneWeather(aspects) {
+        const supportiveAspects = new Set(['conjunction', 'trine', 'sextile']);
+        const challengingAspects = new Set(['square', 'opposition']);
+        return {
+            supportive: aspects
+                .filter((aspect) => supportiveAspects.has(aspect.aspect))
+                .map((aspect) => aspect.id),
+            challenging: aspects
+                .filter((aspect) => challengingAspects.has(aspect.aspect))
+                .map((aspect) => aspect.id),
+        };
+    }
+    /**
+     * Compute transit-to-transit mundane aspects for a single day's positions.
+     *
+     * @param date - Reporting date label used in stable aspect ids
+     * @param positions - Transiting planetary positions for the day
+     * @returns Sorted mundane aspects with orb and applying metadata
+     */
+    getMundaneAspects(date, positions) {
+        const aspects = [];
+        for (let i = 0; i < positions.length; i++) {
+            for (let j = i + 1; j < positions.length; j++) {
+                const planetA = positions[i];
+                const planetB = positions[j];
+                const angle = this.ephem.calculateAspectAngle(planetA.longitude, planetB.longitude);
+                for (const aspect of ASPECTS) {
+                    const orb = Math.abs(angle - aspect.angle);
+                    if (orb > aspect.orb) {
+                        continue;
+                    }
+                    const futureLongitudeA = (planetA.longitude + planetA.speed * 0.1 + 360) % 360;
+                    const futureLongitudeB = (planetB.longitude + planetB.speed * 0.1 + 360) % 360;
+                    const futureAngle = this.ephem.calculateAspectAngle(futureLongitudeA, futureLongitudeB);
+                    const futureOrb = Math.abs(futureAngle - aspect.angle);
+                    aspects.push({
+                        id: `${date}:${planetA.planet}-${aspect.name}-${planetB.planet}`,
+                        planetA: planetA.planet,
+                        planetB: planetB.planet,
+                        aspect: aspect.name,
+                        orb: Number.parseFloat(orb.toFixed(2)),
+                        isApplying: futureOrb < orb,
+                        longitudeA: planetA.longitude,
+                        longitudeB: planetB.longitude,
+                    });
+                }
+            }
+        }
+        return aspects.sort((left, right) => left.orb - right.orb ||
+            left.planetA.localeCompare(right.planetA) ||
+            left.planetB.localeCompare(right.planetB) ||
+            left.aspect.localeCompare(right.aspect));
+    }
+    /**
+     * Build the optional mundane payload for one transit day.
+     *
+     * @param dayUTC - UTC instant representing the day anchor
+     * @param timezone - Reporting timezone used for day labels
+     * @param transitingPlanetIds - Planet ids included in the mundane calculation
+     * @returns Daily mundane bundle with positions, aspects, and weather
+     */
+    getMundaneDay(dayUTC, timezone, transitingPlanetIds) {
+        const localDay = utcToLocal(dayUTC, timezone);
+        const dateLabel = this.formatDateLabel(localDay);
+        const currentJD = this.ephem.dateToJulianDay(dayUTC);
+        const positions = this.ephem.getAllPlanets(currentJD, transitingPlanetIds);
+        const aspects = this.getMundaneAspects(dateLabel, positions);
+        return {
+            date: dateLabel,
+            timezone,
+            positions,
+            aspects,
+            weather: this.getMundaneWeather(aspects),
+        };
+    }
+    /**
+     * Format a local date tuple into the service's canonical YYYY-MM-DD label.
+     */
+    formatDateLabel(localDate) {
+        return `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
+    }
+}