ether-to-astro 1.0.2 → 1.2.0

package/src/astro-service.ts

@@ -3,21 +3,37 @@ import { Temporal } from '@js-temporal/polyfill';
 import { ChartRenderer } from './charts.js';
 import { getDefaultTheme } from './constants.js';
 import { EclipseCalculator } from './eclipses.js';
+import type { McpStartupDefaults } from './entrypoint.js';
 import { EphemerisCalculator } from './ephemeris.js';
 import { formatDateOnly, formatInTimezone } from './formatter.js';
 import { HouseCalculator } from './houses.js';
 import { RiseSetCalculator } from './riseset.js';
-import { addLocalDays, type Disambiguation, localToUTC, utcToLocal } from './time-utils.js';
+import {
+  addLocalDays,
+  type Disambiguation,
+  formatLocalTimestampWithOffset,
+  localToUTC,
+  utcToLocal,
+} from './time-utils.js';
 import { deduplicateTransits, TransitCalculator } from './transits.js';
 import {
+  ASPECTS,
   ASTEROIDS,
+  type AspectType,
+  type ElectionalAspect,
+  type ElectionalContextResponse,
+  type ElectionalHouseSystem,
+  type ElectionalPhaseName,
+  type HouseData,
   type HouseSystem,
   type NatalChart,
   NODES,
   OUTER_PLANETS,
   PERSONAL_PLANETS,
+  PLANET_NAMES,
   PLANETS,
-  type PlanetPositionResponse,
+  type PlanetName,
+  type PlanetPosition,
   type Transit,
   type TransitResponse,
   ZODIAC_SIGNS,
@@ -30,6 +46,7 @@ interface AstroServiceDependencies {
   riseSetCalc?: RiseSetCalculator;
   eclipseCalc?: EclipseCalculator;
   chartRenderer?: ChartRenderer;
+  mcpStartupDefaults?: McpStartupDefaults;
   now?: () => Date;
   writeFile?: (path: string, data: string | Buffer, encoding?: BufferEncoding) => Promise<void>;
 }
@@ -53,15 +70,36 @@ export interface GetTransitsInput {
   categories?: string[];
   include_mundane?: boolean;
   days_ahead?: number;
+  mode?: 'snapshot' | 'best_hit' | 'forecast';
   max_orb?: number;
   exact_only?: boolean;
   applying_only?: boolean;
 }
 
+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;
+}
+
 export interface GetHousesInput {
   system?: string;
 }
 
+export interface GetRisingSignWindowsInput {
+  date: string;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  mode?: 'approximate' | 'exact';
+}
+
 export interface GenerateChartInput {
   theme?: 'light' | 'dark';
   format?: 'svg' | 'png' | 'webp';
@@ -77,7 +115,30 @@ export interface ServiceResult<T> {
   text: string;
 }
 
-export interface ChartServiceResult {
+export interface MundaneAspect {
+  id: string;
+  planetA: PlanetPosition['planet'];
+  planetB: PlanetPosition['planet'];
+  aspect: AspectType;
+  orb: number;
+  isApplying: boolean;
+  longitudeA: number;
+  longitudeB: number;
+}
+
+interface MundaneWeather {
+  supportive: string[];
+  challenging: string[];
+}
+
+interface MundaneDay {
+  date: string;
+  timezone: string;
+  positions: PlanetPosition[];
+  aspects: MundaneAspect[];
+  weather: MundaneWeather;
+}
+interface ChartServiceResult {
   format: 'svg' | 'png' | 'webp';
   outputPath?: string;
   text: string;
@@ -120,6 +181,44 @@ export function parseDateOnlyInput(dateStr: string): {
   return { year, month, day, hour: 12, minute: 0 };
 }
 
+function parseTimeOnlyInput(timeStr: string): { hour: number; minute: number; second: number } {
+  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: ElectionalHouseSystem[] = ['P', 'K', 'W', 'R'];
+
 export class AstroService {
   readonly ephem: EphemerisCalculator;
   readonly transitCalc: TransitCalculator;
@@ -127,6 +226,7 @@ export class AstroService {
   readonly riseSetCalc: RiseSetCalculator;
   readonly eclipseCalc: EclipseCalculator;
   readonly chartRenderer: ChartRenderer;
+  readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
   private readonly now: () => Date;
   private readonly writeFileFn: (
     path: string,
@@ -141,10 +241,72 @@ 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;
   }
 
+  private formatTimestamp(date: Date, timezone: string): string {
+    return formatInTimezone(date, timezone, {
+      weekday: this.mcpStartupDefaults.weekdayLabels ?? false,
+    });
+  }
+
+  private normalizeLongitude(longitude: number): number {
+    return ((longitude % 360) + 360) % 360;
+  }
+
+  private getSignAndDegree(longitude: number): { sign: string; degree: number } {
+    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,
+    };
+  }
+
+  private getHouseNumber(longitude: number, houses: HouseData): number {
+    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;
+  }
+
+  private resolveHouseSystem(natalChart: NatalChart, explicitSystem?: string): HouseSystem {
+    return (explicitSystem ||
+      natalChart.requestedHouseSystem ||
+      this.mcpStartupDefaults.preferredHouseStyle ||
+      natalChart.houseSystem ||
+      'P') as HouseSystem;
+  }
+
+  private resolveTimezones(explicitReportingTimezone?: string, natalTimezone?: string) {
+    return {
+      calculationTimezone: natalTimezone ?? 'UTC',
+      reportingTimezone: this.resolveReportingTimezone(explicitReportingTimezone, natalTimezone),
+    };
+  }
+
+  resolveReportingTimezone(explicitTimezone?: string, natalTimezone?: string): string {
+    return explicitTimezone ?? this.mcpStartupDefaults.preferredTimezone ?? natalTimezone ?? 'UTC';
+  }
+
   async init(): Promise<void> {
     await this.ephem.init();
   }
@@ -200,6 +362,7 @@ export class AstroService {
       planets: positions,
       julianDay: jd,
       houseSystem: houses.system,
+      requestedHouseSystem: requestedHouseSystem ?? undefined,
       utcDateTime: utcComponents,
     };
 
@@ -297,16 +460,31 @@ 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 (!Number.isFinite(maxOrb) || maxOrb < 0) {
+      throw new Error('max_orb must be a finite number >= 0');
     }
-    if (maxOrb < 0) {
-      throw new Error('max_orb must be >= 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: number[] = [];
     if (categories.includes('all')) {
@@ -323,23 +501,29 @@ export class AstroService {
       }
     }
 
-    const timezone = natalChart.location.timezone;
+    const { calculationTimezone, reportingTimezone } = this.resolveTimezones(
+      undefined,
+      natalChart.location.timezone
+    );
 
     let targetDate: Date;
     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: Transit[] = [];
-    const startLocal = utcToLocal(targetDate, timezone);
-    for (let day = 0; day <= daysAhead; day++) {
-      const dayUTC = addLocalDays(startLocal, timezone, day);
+    const transitsByDay = new Map<string, Transit[]>();
+    const transitContext = new WeakMap<Transit, { julianDay: number }>();
+    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(
@@ -347,22 +531,65 @@ export class AstroService {
         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 filterTransits = (transits: Transit[]): Transit[] => {
+      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<number, HouseData>();
+    const planetIdsByName = new Map(
+      Object.entries(PLANET_NAMES).map(([id, name]) => [name, Number(id)])
+    );
+    const getTransitHouses = (julianDay: number): HouseData => {
+      const cached = transitHouseCache.get(julianDay);
+      if (cached) {
+        return cached;
+      }
 
-    const localDate = utcToLocal(targetDate, timezone);
-    const dateLabel = `${localDate.year}-${String(localDate.month).padStart(2, '0')}-${String(localDate.day).padStart(2, '0')}`;
+      const houses = this.houseCalc.calculateHouses(
+        julianDay,
+        natalChart.location.latitude,
+        natalChart.location.longitude,
+        chartHouseSystem
+      );
+      transitHouseCache.set(julianDay, houses);
+      return houses;
+    };
+    const serializeTransit = (t: Transit) => {
+      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) as number,
+              transitHouseJulianDay
+            ).longitude
+          : t.transitLongitude;
 
-    const structuredData: TransitResponse = {
-      date: dateLabel,
-      timezone,
-      transits: filteredTransits.map((t) => ({
+      return {
         transitingPlanet: t.transitingPlanet,
         aspect: t.aspect,
         natalPlanet: t.natalPlanet,
@@ -372,7 +599,42 @@ 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: TransitResponse = {
+      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: Record<string, unknown> = structuredData as unknown as Record<
@@ -381,36 +643,85 @@ export class AstroService {
     >;
     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 mundaneData: PlanetPositionResponse = {
-        date: dateLabel,
-        timezone,
-        positions: currentPositions,
+      const mundaneDays: MundaneDay[] = [];
+      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: 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 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 formatHumanTransit = (t: Transit) => {
+      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}`;
+    };
+    const rangeStr = effectiveDaysAhead > 0 ? ` (next ${effectiveDaysAhead + 1} days)` : '';
+    let transitHeader: string;
+    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,
@@ -418,11 +729,277 @@ export class AstroService {
     };
   }
 
+  private getMundaneWeather(aspects: MundaneAspect[]): MundaneWeather {
+    const supportiveAspects = new Set<AspectType>(['conjunction', 'trine', 'sextile']);
+    const challengingAspects = new Set<AspectType>(['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),
+    };
+  }
+
+  private getMundaneAspects(date: string, positions: PlanetPosition[]): MundaneAspect[] {
+    const aspects: MundaneAspect[] = [];
+
+    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)
+    );
+  }
+
+  private getMundaneDay(dayUTC: Date, timezone: string, transitingPlanetIds: number[]): MundaneDay {
+    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: GetElectionalContextInput): ServiceResult<Record<string, unknown>> {
+    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: Date;
+    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: string[] = [];
+    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: ElectionalContextResponse = {
+      input: {
+        date: input.date,
+        time: input.time,
+        timezone: input.timezone,
+        latitude: input.latitude,
+        longitude: input.longitude,
+        house_system: houses.system as ElectionalHouseSystem,
+        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 as unknown as Record<string, unknown>,
+      text: humanText.join('\n'),
+    };
+  }
+
   getHouses(
     natalChart: NatalChart,
     input: GetHousesInput = {}
   ): ServiceResult<Record<string, unknown>> {
-    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.');
     }
@@ -449,19 +1026,235 @@ export class AstroService {
     };
   }
 
-  getRetrogradePlanets(timezone = 'UTC'): ServiceResult<Record<string, unknown>> {
+  getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>> {
+    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: Date): { sign: string; longitude: number } => {
+      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: Date, right: Date): Date => {
+      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: Date, end: Date, probeStepMs: number): Date[] => {
+      const boundaries: Date[] = [];
+      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: Date[] = [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,
+    };
+  }
+
+  private getElectionalApplyingAspects(
+    positions: PlanetPosition[],
+    orbDegrees: number
+  ): ElectionalAspect[] {
+    const aspects: ElectionalAspect[] = [];
+
+    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)
+    );
+  }
+
+  private isElectionalAspectApplying(
+    from: Pick<PlanetPosition, 'longitude' | 'speed'>,
+    to: Pick<PlanetPosition, 'longitude' | 'speed'>,
+    aspectAngle: number
+  ): boolean {
+    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;
+  }
+
+  private getSignedAngularDifference(fromLongitude: number, toLongitude: number): number {
+    const normalized = ((toLongitude - fromLongitude + 540) % 360) - 180;
+    return normalized === -180 ? 180 : normalized;
+  }
+
+  private getElectionalPhaseName(phaseAngle: number): ElectionalPhaseName {
+    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';
+  }
+
+  private getTraditionalSignRuler(sign: string): PlanetName {
+    const signRulers: Record<string, PlanetName> = {
+      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?: string): ServiceResult<Record<string, unknown>> {
+    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,
     };
 
@@ -475,6 +1268,7 @@ export class AstroService {
 
   async getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>> {
     const timezone = natalChart.location.timezone;
+    const reportingTimezone = this.mcpStartupDefaults.preferredTimezone || timezone;
     const now = this.now();
     const localNow = utcToLocal(now, timezone);
     const localMidnight = {
@@ -507,8 +1301,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')}`;
@@ -519,18 +1313,19 @@ export class AstroService {
     };
   }
 
-  getAsteroidPositions(timezone = 'UTC'): ServiceResult<Record<string, unknown>> {
+  getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>> {
+    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,
     };
 
@@ -547,7 +1342,8 @@ export class AstroService {
     };
   }
 
-  getNextEclipses(timezone = 'UTC'): ServiceResult<Record<string, unknown>> {
+  getNextEclipses(timezone?: string): ServiceResult<Record<string, unknown>> {
+    const resolvedTimezone = this.resolveReportingTimezone(timezone);
     const now = this.now();
     const jd = this.ephem.dateToJulianDay(now);
 
@@ -564,7 +1360,7 @@ export class AstroService {
         maxTime: solarEclipse.maxTime.toISOString(),
       });
       humanLines.push(
-        `Next Solar Eclipse: ${formatInTimezone(solarEclipse.maxTime, timezone)} (${solarEclipse.eclipseType})`
+        `Next Solar Eclipse: ${this.formatTimestamp(solarEclipse.maxTime, resolvedTimezone)} (${solarEclipse.eclipseType})`
       );
     }
 
@@ -575,11 +1371,11 @@ export class AstroService {
         maxTime: lunarEclipse.maxTime.toISOString(),
       });
       humanLines.push(
-        `Next Lunar Eclipse: ${formatInTimezone(lunarEclipse.maxTime, timezone)} (${lunarEclipse.eclipseType})`
+        `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.'
@@ -594,6 +1390,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',
     };