ether-to-astro 1.0.2 → 1.2.0

package/dist/astro-service.js

@@ -7,9 +7,9 @@ import { EphemerisCalculator } from './ephemeris.js';
 import { formatDateOnly, formatInTimezone } from './formatter.js';
 import { HouseCalculator } from './houses.js';
 import { RiseSetCalculator } from './riseset.js';
-import { addLocalDays, localToUTC, utcToLocal } from './time-utils.js';
+import { addLocalDays, formatLocalTimestampWithOffset, localToUTC, utcToLocal, } from './time-utils.js';
 import { deduplicateTransits, TransitCalculator } from './transits.js';
-import { ASTEROIDS, NODES, OUTER_PLANETS, PERSONAL_PLANETS, PLANETS, ZODIAC_SIGNS, } from './types.js';
+import { ASPECTS, ASTEROIDS, NODES, OUTER_PLANETS, PERSONAL_PLANETS, PLANET_NAMES, PLANETS, ZODIAC_SIGNS, } from './types.js';
 export function parseDateOnlyInput(dateStr) {
     const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr);
     if (!match) {
@@ -32,6 +32,38 @@ export function parseDateOnlyInput(dateStr) {
     }
     return { year, month, day, hour: 12, minute: 0 };
 }
+function parseTimeOnlyInput(timeStr) {
+    const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(timeStr);
+    if (!match) {
+        throw new Error(`Invalid time format: expected HH:mm[:ss], got "${timeStr}"`);
+    }
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    const second = match[3] === undefined ? 0 : Number(match[3]);
+    if (hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59) {
+        throw new Error(`Invalid clock time: ${timeStr}`);
+    }
+    try {
+        Temporal.PlainTime.from({ hour, minute, second });
+    }
+    catch {
+        throw new Error(`Invalid clock time: ${timeStr}`);
+    }
+    return { hour, minute, second };
+}
+const ELECTIONAL_CONTEXT_PLANET_IDS = [
+    PLANETS.SUN,
+    PLANETS.MOON,
+    PLANETS.MERCURY,
+    PLANETS.VENUS,
+    PLANETS.MARS,
+    PLANETS.JUPITER,
+    PLANETS.SATURN,
+    PLANETS.URANUS,
+    PLANETS.NEPTUNE,
+    PLANETS.PLUTO,
+];
+const ELECTIONAL_CONTEXT_HOUSE_SYSTEMS = ['P', 'K', 'W', 'R'];
 export class AstroService {
     ephem;
     transitCalc;
@@ -39,6 +71,7 @@ export class AstroService {
     riseSetCalc;
     eclipseCalc;
     chartRenderer;
+    mcpStartupDefaults;
     now;
     writeFileFn;
     constructor(deps = {}) {
@@ -48,9 +81,61 @@ export class AstroService {
         this.riseSetCalc = deps.riseSetCalc ?? new RiseSetCalculator(this.ephem);
         this.eclipseCalc = deps.eclipseCalc ?? new EclipseCalculator(this.ephem);
         this.chartRenderer = deps.chartRenderer ?? new ChartRenderer(this.ephem, this.houseCalc);
+        this.mcpStartupDefaults = Object.freeze({ ...(deps.mcpStartupDefaults ?? {}) });
         this.now = deps.now ?? (() => new Date());
         this.writeFileFn = deps.writeFile ?? writeFile;
     }
+    formatTimestamp(date, timezone) {
+        return formatInTimezone(date, timezone, {
+            weekday: this.mcpStartupDefaults.weekdayLabels ?? false,
+        });
+    }
+    normalizeLongitude(longitude) {
+        return ((longitude % 360) + 360) % 360;
+    }
+    getSignAndDegree(longitude) {
+        const normalized = this.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,
+        };
+    }
+    getHouseNumber(longitude, houses) {
+        const normalized = this.normalizeLongitude(longitude);
+        for (let house = 1; house <= 12; house++) {
+            const start = this.normalizeLongitude(houses.cusps[house]);
+            const nextHouse = house === 12 ? 1 : house + 1;
+            const end = this.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;
+    }
+    resolveHouseSystem(natalChart, explicitSystem) {
+        return (explicitSystem ||
+            natalChart.requestedHouseSystem ||
+            this.mcpStartupDefaults.preferredHouseStyle ||
+            natalChart.houseSystem ||
+            'P');
+    }
+    resolveTimezones(explicitReportingTimezone, natalTimezone) {
+        return {
+            calculationTimezone: natalTimezone ?? 'UTC',
+            reportingTimezone: this.resolveReportingTimezone(explicitReportingTimezone, natalTimezone),
+        };
+    }
+    resolveReportingTimezone(explicitTimezone, natalTimezone) {
+        return explicitTimezone ?? this.mcpStartupDefaults.preferredTimezone ?? natalTimezone ?? 'UTC';
+    }
     async init() {
         await this.ephem.init();
     }
@@ -91,6 +176,7 @@ export class AstroService {
             planets: positions,
             julianDay: jd,
             houseSystem: houses.system,
+            requestedHouseSystem: requestedHouseSystem ?? undefined,
             utcDateTime: utcComponents,
         };
         const sun = positions.find((p) => p.planet === 'Sun');
@@ -170,15 +256,27 @@ export class AstroService {
         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 (daysAhead < 0) {
-            throw new Error('days_ahead must be >= 0');
+        if (!Number.isFinite(daysAhead) || daysAhead < 0) {
+            throw new Error('days_ahead must be a finite number >= 0');
         }
-        if (maxOrb < 0) {
-            throw new Error('max_orb must be >= 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';
         let transitingPlanetIds = [];
         if (categories.includes('all')) {
             transitingPlanetIds = Object.values(PLANETS);
@@ -193,40 +291,70 @@ export class AstroService {
                 transitingPlanetIds.push(...OUTER_PLANETS.filter((p) => !transitingPlanetIds.includes(p)));
             }
         }
-        const timezone = natalChart.location.timezone;
+        const { calculationTimezone, reportingTimezone } = this.resolveTimezones(undefined, natalChart.location.timezone);
         let targetDate;
         if (dateStr) {
             const parsed = parseDateOnlyInput(dateStr);
-            targetDate = localToUTC(parsed, timezone);
+            targetDate = localToUTC(parsed, calculationTimezone);
         }
         else {
             const now = this.now();
-            const localNow = utcToLocal(now, timezone);
+            const localNow = utcToLocal(now, calculationTimezone);
             const localNoon = { ...localNow, hour: 12, minute: 0, second: 0 };
-            targetDate = localToUTC(localNoon, timezone);
+            targetDate = localToUTC(localNoon, calculationTimezone);
         }
         const allTransits = [];
-        const startLocal = utcToLocal(targetDate, timezone);
-        for (let day = 0; day <= daysAhead; day++) {
-            const dayUTC = addLocalDays(startLocal, timezone, day);
+        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 jd = this.ephem.dateToJulianDay(dayUTC);
             const transitingPlanets = this.ephem.getAllPlanets(jd, transitingPlanetIds);
             const transits = this.transitCalc.findTransits(transitingPlanets, natalChart.planets || [], jd);
+            for (const transit of transits) {
+                transitContext.set(transit, { julianDay: jd });
+            }
             allTransits.push(...transits);
+            const dayLocal = utcToLocal(dayUTC, reportingTimezone);
+            const dayLabel = `${dayLocal.year}-${String(dayLocal.month).padStart(2, '0')}-${String(dayLocal.day).padStart(2, '0')}`;
+            transitsByDay.set(dayLabel, transits);
         }
-        let filteredTransits = deduplicateTransits(allTransits);
-        filteredTransits = filteredTransits.filter((t) => t.orb <= maxOrb);
-        if (exactOnly)
-            filteredTransits = filteredTransits.filter((t) => t.exactTime !== undefined);
-        if (applyingOnly)
-            filteredTransits = filteredTransits.filter((t) => t.isApplying);
-        filteredTransits.sort((a, b) => a.orb - b.orb);
-        const localDate = utcToLocal(targetDate, timezone);
-        const dateLabel = `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
-        const structuredData = {
-            date: dateLabel,
-            timezone,
-            transits: filteredTransits.map((t) => ({
+        const filterTransits = (transits) => {
+            let filtered = transits.filter((t) => t.orb <= maxOrb);
+            if (exactOnly)
+                filtered = filtered.filter((t) => t.exactTime !== undefined);
+            if (applyingOnly)
+                filtered = filtered.filter((t) => t.isApplying);
+            filtered.sort((a, b) => a.orb - b.orb);
+            return filtered;
+        };
+        const chartHouseSystem = this.resolveHouseSystem(natalChart);
+        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(([id, name]) => [name, Number(id)]));
+        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 = (t) => {
+            const transitPlacement = this.getSignAndDegree(t.transitLongitude);
+            const natalPlacement = this.getSignAndDegree(t.natalLongitude);
+            const context = transitContext.get(t);
+            const transitHouseJulianDay = t.exactTime
+                ? this.ephem.dateToJulianDay(t.exactTime)
+                : (context?.julianDay ?? this.ephem.dateToJulianDay(targetDate));
+            const transitHouses = getTransitHouses(transitHouseJulianDay);
+            const exactTransitLongitude = t.exactTime && planetIdsByName.has(t.transitingPlanet)
+                ? this.ephem.getPlanetPosition(planetIdsByName.get(t.transitingPlanet), transitHouseJulianDay).longitude
+                : t.transitLongitude;
+            return {
                 transitingPlanet: t.transitingPlanet,
                 aspect: t.aspect,
                 natalPlanet: t.natalPlanet,
@@ -236,41 +364,323 @@ export class AstroService {
                 exactTime: t.exactTime?.toISOString(),
                 transitLongitude: t.transitLongitude,
                 natalLongitude: t.natalLongitude,
-            })),
+                transitSign: transitPlacement.sign,
+                transitDegree: transitPlacement.degree,
+                transitHouse: this.getHouseNumber(exactTransitLongitude, transitHouses),
+                natalSign: natalPlacement.sign,
+                natalDegree: natalPlacement.degree,
+                natalHouse: this.getHouseNumber(t.natalLongitude, natalHouses),
+            };
+        };
+        const filteredTransits = mode === 'forecast'
+            ? filterTransits(deduplicateTransits(allTransits))
+            : filterTransits(deduplicateTransits(allTransits));
+        const localDate = utcToLocal(targetDate, reportingTimezone);
+        const dateLabel = `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
+        const endLocal = utcToLocal(addLocalDays(startLocal, calculationTimezone, effectiveDaysAhead), reportingTimezone);
+        const windowEndLabel = `${endLocal.year}-${String(endLocal.month).padStart(2, '0')}-${String(endLocal.day).padStart(2, '0')}`;
+        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(([a], [b]) => a.localeCompare(b))
+                .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 currentJD = this.ephem.dateToJulianDay(targetDate);
-            const currentPositions = this.ephem.getAllPlanets(currentJD, transitingPlanetIds);
+            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: dateLabel,
-                timezone,
-                positions: currentPositions,
+                date: anchorMundane.date,
+                timezone: anchorMundane.timezone,
+                positions: anchorMundane.positions,
+                aspects: anchorMundane.aspects,
+                days: mundaneDays,
             };
-            responseData = { transits: structuredData, mundane: mundaneData };
-            mundaneText = `\n\nCurrent Planetary Positions:\n\n${currentPositions
+            responseData = { transits: responseData, mundane: mundaneData };
+            mundaneText = `\n\nCurrent Planetary Positions:\n\n${anchorMundane.positions
                 .map((p) => `${p.planet}: ${p.degree.toFixed(1)}° ${p.sign} (${p.isRetrograde ? 'Rx' : 'Direct'})`)
                 .join('\n')}`;
+            if (mode === 'forecast') {
+                mundaneText +=
+                    '\n\nNote: mundane positions remain anchored to the forecast start date in this mode.';
+            }
         }
-        const humanLines = filteredTransits
-            .map((t) => {
-            const exactStr = t.exactTime ? ` - Exact: ${formatInTimezone(t.exactTime, timezone)}` : '';
+        const formatHumanTransit = (t) => {
+            const exactStr = t.exactTime
+                ? ` - Exact: ${this.formatTimestamp(t.exactTime, reportingTimezone)}`
+                : '';
             const applyStr = t.isApplying ? '(applying)' : '(separating)';
             return `${t.transitingPlanet} ${t.aspect} ${t.natalPlanet}: ${t.orb.toFixed(2)}° orb ${applyStr}${exactStr}`;
-        })
-            .join('\n');
-        const rangeStr = daysAhead > 0 ? ` (next ${daysAhead + 1} days)` : '';
-        const transitHeader = filteredTransits.length > 0
-            ? `Transits${rangeStr}:\n\n${humanLines}`
-            : 'No transits found matching the specified criteria.';
+        };
+        const rangeStr = effectiveDaysAhead > 0 ? ` (next ${effectiveDaysAhead + 1} days)` : '';
+        let transitHeader;
+        if (mode === 'forecast') {
+            const forecastLines = Array.from(transitsByDay.entries())
+                .sort(([a], [b]) => a.localeCompare(b))
+                .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,
         };
     }
+    getMundaneWeather(aspects) {
+        const supportiveAspects = new Set(['conjunction', 'trine', 'sextile']);
+        const challengingAspects = new Set(['square', 'opposition']);
+        return {
+            supportive: aspects.filter((a) => supportiveAspects.has(a.aspect)).map((a) => a.id),
+            challenging: aspects.filter((a) => challengingAspects.has(a.aspect)).map((a) => a.id),
+        };
+    }
+    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((a, b) => a.orb - b.orb ||
+            a.planetA.localeCompare(b.planetA) ||
+            a.planetB.localeCompare(b.planetB) ||
+            a.aspect.localeCompare(b.aspect));
+    }
+    getMundaneDay(dayUTC, timezone, transitingPlanetIds) {
+        const localDay = utcToLocal(dayUTC, timezone);
+        const dateLabel = `${localDay.year}-${String(localDay.month).padStart(2, '0')}-${String(localDay.day).padStart(2, '0')}`;
+        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),
+        };
+    }
+    getElectionalContext(input) {
+        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 houseSystem = input.house_system ?? 'P';
+        if (!ELECTIONAL_CONTEXT_HOUSE_SYSTEMS.includes(houseSystem)) {
+            throw new Error(`Invalid house_system: ${houseSystem} (must be one of ${ELECTIONAL_CONTEXT_HOUSE_SYSTEMS.join(', ')})`);
+        }
+        const includeRulerBasics = input.include_ruler_basics ?? false;
+        const includePlanetaryApplications = input.include_planetary_applications ?? true;
+        const orbDegrees = input.orb_degrees ?? 3;
+        if (!Number.isFinite(orbDegrees) || orbDegrees < 0.1 || orbDegrees > 10) {
+            throw new Error(`Invalid orb_degrees: ${orbDegrees} (must be between 0.1 and 10)`);
+        }
+        const parsedDate = parseDateOnlyInput(input.date);
+        const parsedTime = parseTimeOnlyInput(input.time);
+        let instantUtc;
+        try {
+            instantUtc = localToUTC({
+                year: parsedDate.year,
+                month: parsedDate.month,
+                day: parsedDate.day,
+                hour: parsedTime.hour,
+                minute: parsedTime.minute,
+                second: parsedTime.second,
+            }, input.timezone, 'reject');
+        }
+        catch (error) {
+            if (error instanceof RangeError) {
+                throw new Error(`Invalid local electional time: ${input.date} ${input.time} in ${input.timezone} is ambiguous or nonexistent due to a DST transition.`);
+            }
+            throw error;
+        }
+        const jdUt = this.ephem.dateToJulianDay(instantUtc);
+        const houses = this.houseCalc.calculateHouses(jdUt, input.latitude, input.longitude, houseSystem);
+        const positions = this.ephem.getAllPlanets(jdUt, ELECTIONAL_CONTEXT_PLANET_IDS);
+        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 electional context.');
+        }
+        const sunHorizontal = this.ephem.getHorizontalCoordinates(jdUt, sun, input.longitude, input.latitude);
+        const sunAltitudeDegrees = Number.parseFloat(sunHorizontal.trueAltitude.toFixed(2));
+        const isDayChart = sunAltitudeDegrees >= 0;
+        const applyingAspects = includePlanetaryApplications
+            ? this.getElectionalApplyingAspects(positions, orbDegrees)
+            : undefined;
+        const moonApplyingAspects = applyingAspects?.filter((aspect) => aspect.from_body === 'Moon' || aspect.to_body === 'Moon');
+        const phaseAngle = Number.parseFloat(((((moon.longitude - sun.longitude) % 360) + 360) % 360).toFixed(2));
+        const warnings = [];
+        if (Math.abs(sunAltitudeDegrees) < 0.5) {
+            warnings.push('Sun is near the horizon; day/night classification is close to the boundary.');
+        }
+        warnings.push('Moon void-of-course is deferred in this slice and returns null.');
+        if (houses.system !== houseSystem) {
+            warnings.push(`House calculation fell back from ${houseSystem} to ${houses.system} for this location.`);
+        }
+        const ascLongitude = ((houses.ascendant % 360) + 360) % 360;
+        const ascSign = ZODIAC_SIGNS[Math.floor(ascLongitude / 30)];
+        const response = {
+            input: {
+                date: input.date,
+                time: input.time,
+                timezone: input.timezone,
+                latitude: input.latitude,
+                longitude: input.longitude,
+                house_system: houses.system,
+                instant_utc: instantUtc.toISOString(),
+                jd_ut: Number.parseFloat(jdUt.toFixed(8)),
+            },
+            ascendant: {
+                longitude: Number.parseFloat(ascLongitude.toFixed(4)),
+                sign: ascSign,
+                degree_in_sign: Number.parseFloat((ascLongitude % 30).toFixed(4)),
+            },
+            sect: {
+                is_day_chart: isDayChart,
+                sun_altitude_degrees: sunAltitudeDegrees,
+                classification: isDayChart ? 'day' : 'night',
+            },
+            moon: {
+                longitude: Number.parseFloat(moon.longitude.toFixed(4)),
+                sign: moon.sign,
+                phase_angle: phaseAngle,
+                phase_name: this.getElectionalPhaseName(phaseAngle),
+                is_void_of_course: null,
+                ...(moonApplyingAspects !== undefined ? { applying_aspects: moonApplyingAspects } : {}),
+            },
+            meta: {
+                deterministic: true,
+                requires_natal: false,
+                warnings,
+                deferred_features: [
+                    'robust_void_of_course',
+                    'detailed_ruler_condition',
+                    'house_context',
+                    'natal_overlays',
+                ],
+            },
+        };
+        if (applyingAspects) {
+            response.applying_aspects = applyingAspects;
+        }
+        if (includeRulerBasics) {
+            const rulerBody = this.getTraditionalSignRuler(ascSign);
+            const rulerPosition = positions.find((position) => position.planet === rulerBody);
+            if (!rulerPosition) {
+                throw new Error(`Ephemeris failed to compute ASC ruler position for ${rulerBody}.`);
+            }
+            response.ruler_basics = {
+                asc_sign_ruler: {
+                    body: rulerBody,
+                    longitude: Number.parseFloat(rulerPosition.longitude.toFixed(4)),
+                    sign: rulerPosition.sign,
+                    speed: Number.parseFloat(rulerPosition.speed.toFixed(6)),
+                    is_retrograde: rulerPosition.isRetrograde,
+                },
+            };
+        }
+        const humanText = [
+            `Electional context for ${input.date} ${input.time} (${input.timezone})`,
+            '',
+            `Ascendant: ${response.ascendant.degree_in_sign.toFixed(2)}° ${response.ascendant.sign}`,
+            `Sect: ${response.sect.classification} (${response.sect.sun_altitude_degrees.toFixed(2)}° Sun altitude)`,
+            `Moon: ${response.moon.phase_name} in ${response.moon.sign} (${response.moon.phase_angle.toFixed(2)}° phase angle)`,
+        ];
+        if (includePlanetaryApplications) {
+            const topLevelAspectText = applyingAspects && applyingAspects.length > 0
+                ? applyingAspects
+                    .slice(0, 5)
+                    .map((aspect) => `${aspect.from_body} ${aspect.aspect} ${aspect.to_body} (${aspect.orb.toFixed(2)}°)`)
+                    .join('\n')
+                : 'No applying aspects found within the configured orb.';
+            humanText.push('', 'Applying Aspects:', topLevelAspectText);
+        }
+        if (response.ruler_basics) {
+            humanText.push('', `ASC Ruler: ${response.ruler_basics.asc_sign_ruler.body} in ${response.ruler_basics.asc_sign_ruler.sign} (${response.ruler_basics.asc_sign_ruler.longitude.toFixed(2)}°)`);
+        }
+        if (warnings.length > 0) {
+            humanText.push('', `Warnings: ${warnings.join(' ')}`);
+        }
+        return {
+            data: response,
+            text: humanText.join('\n'),
+        };
+    }
     getHouses(natalChart, input = {}) {
-        const system = input.system || natalChart.houseSystem || 'P';
+        const system = this.resolveHouseSystem(natalChart, input.system);
         if (!natalChart.julianDay) {
             throw new Error('Natal chart is missing julianDay. Re-run set_natal_chart to fix.');
         }
@@ -288,17 +698,203 @@ export class AstroService {
             text: humanText,
         };
     }
-    getRetrogradePlanets(timezone = 'UTC') {
+    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 getAscSign = (date) => {
+            const jd = this.ephem.dateToJulianDay(date);
+            const houses = this.houseCalc.calculateHouses(jd, input.latitude, input.longitude, 'P');
+            const normalized = ((houses.ascendant % 360) + 360) % 360;
+            return { sign: ZODIAC_SIGNS[Math.floor(normalized / 30)], longitude: normalized };
+        };
+        const refineBoundary = (left, right) => {
+            const leftSign = getAscSign(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 = getAscSign(mid).sign;
+                if (midSign === leftSign) {
+                    lo = mid;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            return hi;
+        };
+        const findSignTransitionsInBucket = (start, end, probeStepMs) => {
+            const boundaries = [];
+            let probeCursor = start;
+            let currentSign = getAscSign(probeCursor).sign;
+            while (probeCursor < end) {
+                const probeNext = new Date(Math.min(probeCursor.getTime() + probeStepMs, end.getTime()));
+                const nextSign = getAscSign(probeNext).sign;
+                if (nextSign !== currentSign) {
+                    boundaries.push(mode === 'exact' ? refineBoundary(probeCursor, probeNext) : probeNext);
+                }
+                probeCursor = probeNext;
+                currentSign = nextSign;
+            }
+            return boundaries;
+        };
+        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(...findSignTransitionsInBucket(cursor, next, probeStepMs));
+            cursor = next;
+        }
+        boundaries.push(dayEndUtc);
+        const windows = boundaries.slice(0, -1).map((start, i) => {
+            const end = boundaries[i + 1];
+            const sample = new Date((start.getTime() + end.getTime()) / 2);
+            const sign = getAscSign(sample).sign;
+            return {
+                sign,
+                start: formatLocalTimestampWithOffset(start, input.timezone),
+                end: formatLocalTimestampWithOffset(end, input.timezone),
+                durationMinutes: Math.round((end.getTime() - start.getTime()) / 60000),
+            };
+        });
+        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,
+        };
+    }
+    getElectionalApplyingAspects(positions, orbDegrees) {
+        const aspects = [];
+        for (let i = 0; i < positions.length; i++) {
+            for (let j = i + 1; j < positions.length; j++) {
+                const from = positions[i];
+                const to = positions[j];
+                const currentAngle = this.ephem.calculateAspectAngle(from.longitude, to.longitude);
+                for (const aspect of ASPECTS) {
+                    const orb = Math.abs(currentAngle - aspect.angle);
+                    if (orb > aspect.orb || orb > orbDegrees) {
+                        continue;
+                    }
+                    const applying = this.isElectionalAspectApplying(from, to, aspect.angle);
+                    if (!applying) {
+                        continue;
+                    }
+                    aspects.push({
+                        from_body: from.planet,
+                        to_body: to.planet,
+                        aspect: aspect.name,
+                        orb: Number.parseFloat(orb.toFixed(4)),
+                        applying: true,
+                    });
+                }
+            }
+        }
+        return aspects.sort((a, b) => a.orb - b.orb ||
+            a.from_body.localeCompare(b.from_body) ||
+            a.to_body.localeCompare(b.to_body) ||
+            a.aspect.localeCompare(b.aspect));
+    }
+    isElectionalAspectApplying(from, to, aspectAngle) {
+        const signedSeparation = this.getSignedAngularDifference(from.longitude, to.longitude);
+        const currentSeparation = Math.abs(signedSeparation);
+        if (currentSeparation === aspectAngle) {
+            return false;
+        }
+        const separationRate = Math.sign(signedSeparation || 1) * (to.speed - from.speed);
+        if (separationRate === 0) {
+            return false;
+        }
+        return currentSeparation < aspectAngle ? separationRate > 0 : separationRate < 0;
+    }
+    getSignedAngularDifference(fromLongitude, toLongitude) {
+        const normalized = ((toLongitude - fromLongitude + 540) % 360) - 180;
+        return normalized === -180 ? 180 : normalized;
+    }
+    getElectionalPhaseName(phaseAngle) {
+        if (phaseAngle < 45)
+            return 'new';
+        if (phaseAngle < 90)
+            return 'crescent';
+        if (phaseAngle < 135)
+            return 'first_quarter';
+        if (phaseAngle < 180)
+            return 'gibbous';
+        if (phaseAngle < 225)
+            return 'full';
+        if (phaseAngle < 270)
+            return 'disseminating';
+        if (phaseAngle < 315)
+            return 'last_quarter';
+        return 'balsamic';
+    }
+    getTraditionalSignRuler(sign) {
+        const signRulers = {
+            Aries: 'Mars',
+            Taurus: 'Venus',
+            Gemini: 'Mercury',
+            Cancer: 'Moon',
+            Leo: 'Sun',
+            Virgo: 'Mercury',
+            Libra: 'Venus',
+            Scorpio: 'Mars',
+            Sagittarius: 'Jupiter',
+            Capricorn: 'Saturn',
+            Aquarius: 'Saturn',
+            Pisces: 'Jupiter',
+        };
+        return signRulers[sign] ?? 'Mars';
+    }
+    getRetrogradePlanets(timezone) {
+        const resolvedTimezone = this.resolveReportingTimezone(timezone);
         const now = this.now();
         const jd = this.ephem.dateToJulianDay(now);
         const allPlanetIds = Object.values(PLANETS);
         const positions = this.ephem.getAllPlanets(jd, allPlanetIds);
         const retrograde = positions.filter((p) => p.isRetrograde);
-        const localNow = utcToLocal(now, timezone);
+        const localNow = utcToLocal(now, resolvedTimezone);
         const dateLabel = `${localNow.year}-${String(localNow.month).padStart(2, '0')}-${String(localNow.day).padStart(2, '0')}`;
         const structuredData = {
             date: dateLabel,
-            timezone,
+            timezone: resolvedTimezone,
             planets: retrograde,
         };
         const humanText = retrograde.length === 0
@@ -308,6 +904,7 @@ export class AstroService {
     }
     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 = {
@@ -332,8 +929,8 @@ export class AstroService {
         };
         const humanText = `Rise/Set Times:\n\n${results
             .map((r) => {
-            const rise = r.rise ? formatInTimezone(r.rise, timezone) : 'none';
-            const set = r.set ? formatInTimezone(r.set, timezone) : 'none';
+            const rise = r.rise ? this.formatTimestamp(r.rise, reportingTimezone) : 'none';
+            const set = r.set ? this.formatTimestamp(r.set, reportingTimezone) : 'none';
             return `${r.planet}: Rise ${rise}, Set ${set}`;
         })
             .join('\n')}`;
@@ -342,16 +939,17 @@ export class AstroService {
             text: humanText,
         };
     }
-    getAsteroidPositions(timezone = 'UTC') {
+    getAsteroidPositions(timezone) {
+        const resolvedTimezone = this.resolveReportingTimezone(timezone);
         const now = this.now();
         const jd = this.ephem.dateToJulianDay(now);
         const asteroidIds = [...ASTEROIDS, ...NODES];
         const positions = this.ephem.getAllPlanets(jd, asteroidIds);
-        const localNow = utcToLocal(now, timezone);
+        const localNow = utcToLocal(now, resolvedTimezone);
         const dateLabel = `${localNow.year}-${String(localNow.month).padStart(2, '0')}-${String(localNow.day).padStart(2, '0')}`;
         const structuredData = {
             date: dateLabel,
-            timezone,
+            timezone: resolvedTimezone,
             positions,
         };
         const humanText = `Asteroid & Node Positions:\n\n${positions
@@ -365,7 +963,8 @@ export class AstroService {
             text: humanText,
         };
     }
-    getNextEclipses(timezone = 'UTC') {
+    getNextEclipses(timezone) {
+        const resolvedTimezone = this.resolveReportingTimezone(timezone);
         const now = this.now();
         const jd = this.ephem.dateToJulianDay(now);
         const solarEclipse = this.eclipseCalc.findNextSolarEclipse(jd);
@@ -378,7 +977,7 @@ export class AstroService {
                 eclipseType: solarEclipse.eclipseType,
                 maxTime: solarEclipse.maxTime.toISOString(),
             });
-            humanLines.push(`Next Solar Eclipse: ${formatInTimezone(solarEclipse.maxTime, timezone)} (${solarEclipse.eclipseType})`);
+            humanLines.push(`Next Solar Eclipse: ${this.formatTimestamp(solarEclipse.maxTime, resolvedTimezone)} (${solarEclipse.eclipseType})`);
         }
         if (lunarEclipse) {
             eclipses.push({
@@ -386,9 +985,9 @@ export class AstroService {
                 eclipseType: lunarEclipse.eclipseType,
                 maxTime: lunarEclipse.maxTime.toISOString(),
             });
-            humanLines.push(`Next Lunar Eclipse: ${formatInTimezone(lunarEclipse.maxTime, timezone)} (${lunarEclipse.eclipseType})`);
+            humanLines.push(`Next Lunar Eclipse: ${this.formatTimestamp(lunarEclipse.maxTime, resolvedTimezone)} (${lunarEclipse.eclipseType})`);
         }
-        const structuredData = { timezone, eclipses };
+        const structuredData = { timezone: resolvedTimezone, eclipses };
         const humanText = eclipses.length === 0
             ? 'No eclipses found in the near future.'
             : `Upcoming Eclipses:\n\n${humanLines.join('\n')}`;
@@ -400,6 +999,11 @@ export class AstroService {
             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',
         };