ether-to-astro 1.0.2 → 1.2.0

package/tests/unit/astro-service.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { AstroService, parseDateOnlyInput } from '../../src/astro-service.js';
+import type { McpStartupDefaults } from '../../src/entrypoint.js';
 import type { NatalChart, PlanetPosition, RiseSetTime } from '../../src/types.js';
 
 function makePlanet(planet: PlanetPosition['planet'], longitude: number): PlanetPosition {
@@ -28,12 +29,22 @@ function makeNatalChart(): NatalChart {
   };
 }
 
-function makeService() {
+function makeService(mcpStartupDefaults: McpStartupDefaults = {}) {
   const ephem = {
     eph: {},
     init: vi.fn(async () => {}),
-    dateToJulianDay: vi.fn(() => 2451545),
+    dateToJulianDay: vi.fn((date: Date) => date.getTime() / 86400000 + 2440587.5),
+    calculateAspectAngle: vi.fn((a: number, b: number) => {
+      const diff = Math.abs(a - b);
+      return diff > 180 ? 360 - diff : diff;
+    }),
+    getHorizontalCoordinates: vi.fn(() => ({
+      azimuth: 180,
+      trueAltitude: 25,
+      apparentAltitude: 25,
+    })),
     getAllPlanets: vi.fn(() => [makePlanet('Sun', 204), makePlanet('Moon', 270)]),
+    getPlanetPosition: vi.fn((planetId: number) => makePlanet(planetId === 1 ? 'Moon' : 'Sun', 100)),
   };
   const houseCalc = {
     calculateHouses: vi.fn(() => ({
@@ -96,6 +107,7 @@ function makeService() {
     riseSetCalc: riseSetCalc as any,
     eclipseCalc: eclipseCalc as any,
     chartRenderer: chartRenderer as any,
+    mcpStartupDefaults,
     writeFile,
     now,
   });
@@ -166,9 +178,15 @@ describe('When using AstroService', () => {
     ).toThrow(/Sun\/Moon/);
   });
 
-  it('Given transit filters, then getTransits returns filtered data and optional mundane payload', () => {
-    const { service } = makeService();
+  it('Given transit filters, then getTransits returns filtered data plus mundane aspects and weather for date ranges', () => {
+    const { service, ephem } = makeService();
     const natal = makeNatalChart();
+    ephem.getAllPlanets.mockReturnValue([
+      { ...makePlanet('Sun', 0), speed: 1 },
+      { ...makePlanet('Moon', 90), speed: 1 },
+      { ...makePlanet('Mars', 120), speed: 1 },
+    ]);
+
     const result = service.getTransits(natal, {
       include_mundane: true,
       days_ahead: 1,
@@ -179,7 +197,407 @@ describe('When using AstroService', () => {
 
     expect(result.data).toHaveProperty('transits');
     expect(result.data).toHaveProperty('mundane');
-    expect(result.text).toContain('Transits');
+    const mundane = (result.data as any).mundane;
+    expect(mundane).toMatchObject({
+      date: '2024-03-26',
+      timezone: 'America/Los_Angeles',
+    });
+    expect(mundane.aspects).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          planetA: 'Sun',
+          planetB: 'Moon',
+          aspect: 'square',
+          orb: 0,
+          isApplying: false,
+        }),
+        expect.objectContaining({
+          planetA: 'Sun',
+          planetB: 'Mars',
+          aspect: 'trine',
+          orb: 0,
+          isApplying: false,
+        }),
+      ])
+    );
+    expect(mundane.days).toHaveLength(2);
+    expect(mundane.days[1]).toMatchObject({
+      date: '2024-03-27',
+      timezone: 'America/Los_Angeles',
+    });
+    expect(mundane.days[1].aspects).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          planetA: 'Sun',
+          planetB: 'Moon',
+          aspect: 'square',
+        }),
+      ])
+    );
+    expect(result.text).toContain('Current Planetary Positions');
+  });
+
+  it('Given stateless electional inputs, then getElectionalContext returns deterministic ascendant, sect, moon, and optional ruler basics', () => {
+    const { service, ephem } = makeService();
+    ephem.getAllPlanets.mockReturnValue([
+      { ...makePlanet('Sun', 0), sign: 'Aries', speed: 1 },
+      { ...makePlanet('Moon', 58), sign: 'Taurus', speed: 13 },
+      { ...makePlanet('Mercury', 120), sign: 'Leo', speed: 1.2 },
+      { ...makePlanet('Venus', 180), sign: 'Libra', speed: 1.1 },
+      { ...makePlanet('Mars', 240), sign: 'Sagittarius', speed: 0.7 },
+      { ...makePlanet('Jupiter', 300), sign: 'Aquarius', speed: 0.2 },
+      { ...makePlanet('Saturn', 315), sign: 'Aquarius', speed: 0.05, isRetrograde: true },
+      { ...makePlanet('Uranus', 30), sign: 'Taurus', speed: 0.03 },
+      { ...makePlanet('Neptune', 330), sign: 'Pisces', speed: 0.02 },
+      { ...makePlanet('Pluto', 270), sign: 'Capricorn', speed: 0.01 },
+    ]);
+
+    const result = service.getElectionalContext({
+      date: '2026-03-28',
+      time: '09:30',
+      timezone: 'America/Los_Angeles',
+      latitude: 37.7749,
+      longitude: -122.4194,
+      include_ruler_basics: true,
+    });
+
+    expect(result.data).toMatchObject({
+      input: {
+        date: '2026-03-28',
+        time: '09:30',
+        timezone: 'America/Los_Angeles',
+        house_system: 'W',
+      },
+      ascendant: {
+        sign: 'Capricorn',
+      },
+      sect: {
+        is_day_chart: true,
+        classification: 'day',
+        sun_altitude_degrees: 25,
+      },
+      moon: {
+        sign: 'Taurus',
+        phase_name: 'crescent',
+        is_void_of_course: null,
+      },
+      ruler_basics: {
+        asc_sign_ruler: {
+          body: 'Saturn',
+          sign: 'Aquarius',
+          is_retrograde: true,
+        },
+      },
+      meta: {
+        deterministic: true,
+        requires_natal: false,
+      },
+    });
+    expect((result.data as any).applying_aspects).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          from_body: 'Sun',
+          to_body: 'Moon',
+          aspect: 'sextile',
+          applying: true,
+        }),
+      ])
+    );
+    expect((result.data as any).meta.warnings).toContain(
+      'Moon void-of-course is deferred in this slice and returns null.'
+    );
+    expect(result.text).toContain('Electional context');
+  });
+
+  it('Given electional toggles and invalid inputs, then getElectionalContext honors the raw contract and validates clearly', () => {
+    const { service, ephem } = makeService();
+    ephem.getAllPlanets.mockReturnValue([
+      { ...makePlanet('Sun', 0), sign: 'Aries', speed: 1 },
+      { ...makePlanet('Moon', 120), sign: 'Leo', speed: 1 },
+      { ...makePlanet('Mercury', 210), sign: 'Scorpio', speed: 1 },
+      { ...makePlanet('Venus', 300), sign: 'Aquarius', speed: 1 },
+      { ...makePlanet('Mars', 45), sign: 'Taurus', speed: 1 },
+      { ...makePlanet('Jupiter', 90), sign: 'Cancer', speed: 0.1 },
+      { ...makePlanet('Saturn', 180), sign: 'Libra', speed: 0.1 },
+      { ...makePlanet('Uranus', 240), sign: 'Sagittarius', speed: 0.1 },
+      { ...makePlanet('Neptune', 270), sign: 'Capricorn', speed: 0.1 },
+      { ...makePlanet('Pluto', 330), sign: 'Pisces', speed: 0.1 },
+    ]);
+
+    const result = service.getElectionalContext({
+      date: '2026-03-28',
+      time: '09:30:15',
+      timezone: 'UTC',
+      latitude: 40.7,
+      longitude: -74,
+      include_planetary_applications: false,
+    });
+
+    expect((result.data as any).applying_aspects).toBeUndefined();
+    expect((result.data as any).moon.applying_aspects).toBeUndefined();
+    expect((result.data as any).ruler_basics).toBeUndefined();
+    expect(result.text).not.toContain('Applying Aspects:');
+
+    expect(() =>
+      service.getElectionalContext({
+        date: '2026-03-28',
+        time: '25:61',
+        timezone: 'UTC',
+        latitude: 40.7,
+        longitude: -74,
+      })
+    ).toThrow(/Invalid clock time/);
+
+    expect(() =>
+      service.getElectionalContext({
+        date: '2026-03-28',
+        time: '09:30',
+        timezone: 'UTC',
+        latitude: 40.7,
+        longitude: -74,
+        orb_degrees: 11,
+      })
+    ).toThrow(/Invalid orb_degrees/);
+  });
+
+  it('Given DST-gap or overlap electional times, then getElectionalContext rejects ambiguous local instants', () => {
+    const { service } = makeService();
+
+    expect(() =>
+      service.getElectionalContext({
+        date: '2026-03-08',
+        time: '02:30',
+        timezone: 'America/Los_Angeles',
+        latitude: 37.7749,
+        longitude: -122.4194,
+      })
+    ).toThrow(/ambiguous or nonexistent due to a DST transition/);
+
+    expect(() =>
+      service.getElectionalContext({
+        date: '2026-11-01',
+        time: '01:30',
+        timezone: 'America/Los_Angeles',
+        latitude: 37.7749,
+        longitude: -122.4194,
+      })
+    ).toThrow(/ambiguous or nonexistent due to a DST transition/);
+  });
+
+  it('Given omitted mode and days_ahead 0, then getTransits resolves to snapshot semantics', () => {
+    const { service, transitCalc } = makeService();
+    const result = service.getTransits(makeNatalChart(), {});
+
+    expect(transitCalc.findTransits).toHaveBeenCalledTimes(1);
+    expect(result.data).toMatchObject({
+      mode: 'snapshot',
+      mode_source: 'legacy_default',
+      days_ahead: 0,
+      window_start: '2024-03-26',
+      window_end: '2024-03-26',
+    });
+    expect(result.text).toContain('Transit snapshot');
+  });
+
+  it('Given omitted mode and days_ahead > 0, then getTransits resolves to best_hit semantics', () => {
+    const { service, transitCalc } = makeService();
+    const result = service.getTransits(makeNatalChart(), { days_ahead: 2 });
+
+    expect(transitCalc.findTransits).toHaveBeenCalledTimes(3);
+    expect(result.data).toMatchObject({
+      mode: 'best_hit',
+      mode_source: 'legacy_default',
+      days_ahead: 2,
+      window_start: '2024-03-26',
+      window_end: '2024-03-28',
+    });
+    expect(result.text).toContain('Best-hit transits');
+  });
+
+  it('Given explicit snapshot mode with days_ahead, then only one day is queried and reported', () => {
+    const { service, transitCalc } = makeService();
+    const result = service.getTransits(makeNatalChart(), { mode: 'snapshot', days_ahead: 5 });
+
+    expect(transitCalc.findTransits).toHaveBeenCalledTimes(1);
+    expect(result.data).toMatchObject({
+      mode: 'snapshot',
+      mode_source: 'explicit',
+      days_ahead: 0,
+      window_start: '2024-03-26',
+      window_end: '2024-03-26',
+    });
+  });
+
+  it('Given transit placement metadata, then all transit modes include additive sign, degree, and house fields', () => {
+    const { service } = makeService();
+
+    const snapshot = service.getTransits(makeNatalChart(), { mode: 'snapshot' });
+    const bestHit = service.getTransits(makeNatalChart(), { mode: 'best_hit', days_ahead: 1 });
+    const forecast = service.getTransits(makeNatalChart(), { mode: 'forecast', days_ahead: 1 });
+
+    expect((snapshot.data as any).transits[0]).toMatchObject({
+      transitSign: 'Cancer',
+      transitDegree: 10,
+      transitHouse: 7,
+      natalSign: 'Aries',
+      natalDegree: 10,
+      natalHouse: 4,
+      transitLongitude: 100,
+      natalLongitude: 10,
+    });
+    expect((bestHit.data as any).transits[0]).toMatchObject({
+      transitSign: 'Cancer',
+      transitDegree: 10,
+      transitHouse: 7,
+      natalSign: 'Aries',
+      natalDegree: 10,
+      natalHouse: 4,
+    });
+    expect((forecast.data as any).forecast[0].transits[0]).toMatchObject({
+      transitSign: 'Cancer',
+      transitDegree: 10,
+      transitHouse: 7,
+      natalSign: 'Aries',
+      natalDegree: 10,
+      natalHouse: 4,
+    });
+  });
+
+  it('Given a transit near a sign boundary, then placement degree never rounds up to 30.00 within the same sign', () => {
+    const { service, transitCalc } = makeService();
+    transitCalc.findTransits.mockReturnValue([
+      {
+        transitingPlanet: 'Sun',
+        natalPlanet: 'Sun',
+        aspect: 'conjunction',
+        orb: 0.01,
+        isApplying: true,
+        exactTimeStatus: 'within_preview',
+        transitLongitude: 29.999,
+        natalLongitude: 10,
+        exactTime: undefined,
+      },
+    ]);
+
+    const result = service.getTransits(makeNatalChart(), { mode: 'snapshot' });
+
+    expect((result.data as any).transits[0]).toMatchObject({
+      transitSign: 'Taurus',
+      transitDegree: 0,
+    });
+  });
+
+  it('Given forecast mode across multiple days, then response preserves day-grouped transits with per-day dedupe', () => {
+    const { service, transitCalc } = makeService();
+    transitCalc.findTransits
+      .mockReturnValueOnce([
+        {
+          transitingPlanet: 'Mars',
+          natalPlanet: 'Sun',
+          aspect: 'square',
+          orb: 1.25,
+          isApplying: true,
+          exactTimeStatus: 'within_preview',
+          transitLongitude: 100,
+          natalLongitude: 10,
+          exactTime: new Date('2024-03-26T12:00:00Z'),
+        },
+        {
+          transitingPlanet: 'Mars',
+          natalPlanet: 'Sun',
+          aspect: 'square',
+          orb: 0.75,
+          isApplying: true,
+          exactTimeStatus: 'within_preview',
+          transitLongitude: 100.5,
+          natalLongitude: 10,
+          exactTime: new Date('2024-03-26T13:00:00Z'),
+        },
+      ])
+      .mockReturnValueOnce([
+        {
+          transitingPlanet: 'Mars',
+          natalPlanet: 'Sun',
+          aspect: 'square',
+          orb: 0.5,
+          isApplying: false,
+          exactTimeStatus: 'within_preview',
+          transitLongitude: 101,
+          natalLongitude: 10,
+          exactTime: new Date('2024-03-27T12:00:00Z'),
+        },
+      ]);
+
+    const result = service.getTransits(makeNatalChart(), { mode: 'forecast', days_ahead: 1 });
+
+    expect(result.data).toMatchObject({
+      mode: 'forecast',
+      mode_source: 'explicit',
+      days_ahead: 1,
+      window_start: '2024-03-26',
+      window_end: '2024-03-27',
+      forecast: [
+        { date: '2024-03-26', transits: [{ orb: 0.75 }] },
+        { date: '2024-03-27', transits: [{ orb: 0.5 }] },
+      ],
+    });
+    expect(((result.data as any).forecast[0].transits as Array<unknown>)).toHaveLength(1);
+    expect(result.text).toContain('Forecast transits');
+    expect(result.text).toContain('2024-03-26');
+    expect(result.text).toContain('2024-03-27');
+  });
+
+  it('Given non-finite transit numeric filters, then getTransits throws validation errors before mundane expansion', () => {
+    const { service } = makeService();
+    const natal = makeNatalChart();
+
+    expect(() =>
+      service.getTransits(natal, {
+        include_mundane: true,
+        days_ahead: Number.NaN,
+      })
+    ).toThrow(/days_ahead must be a finite number >= 0/);
+
+    expect(() =>
+      service.getTransits(natal, {
+        max_orb: Number.NaN,
+      })
+    ).toThrow(/max_orb must be a finite number >= 0/);
+  });
+
+  it('Given a resolved whole-sign natal house system, then transit placement uses that same system for natal and transit houses', () => {
+    const { service, houseCalc } = makeService();
+    const polarNatal = {
+      ...makeNatalChart(),
+      location: { latitude: 78, longitude: 15, timezone: 'UTC' },
+      houseSystem: 'W' as const,
+      julianDay: 2451545,
+    };
+    houseCalc.calculateHouses.mockReturnValue({
+      ascendant: 120,
+      mc: 210,
+      cusps: [0, 120, 150, 180, 210, 240, 270, 300, 330, 0, 30, 60, 90],
+      system: 'W' as const,
+    });
+
+    const result = service.getTransits(polarNatal, { mode: 'snapshot' });
+
+    expect(houseCalc.calculateHouses).toHaveBeenCalledWith(
+      polarNatal.julianDay,
+      polarNatal.location.latitude,
+      polarNatal.location.longitude,
+      'W'
+    );
+    expect(houseCalc.calculateHouses).toHaveBeenCalledWith(
+      expect.any(Number),
+      polarNatal.location.latitude,
+      polarNatal.location.longitude,
+      'W'
+    );
+    expect((result.data as any).transits[0]).toMatchObject({
+      transitHouse: 12,
+      natalHouse: 9,
+    });
   });
 
   it('Given exact-time lookup metadata, then getTransits serializes exactTimeStatus', () => {
@@ -215,6 +633,205 @@ describe('When using AstroService', () => {
     expect(result.text).toContain('Rise/Set Times');
   });
 
+  it('Given MCP startup defaults, then reporting timezone fallback and status expose deterministic config', () => {
+    const { service } = makeService({
+      preferredTimezone: 'America/New_York',
+      preferredHouseStyle: 'W',
+      weekdayLabels: true,
+    });
+
+    expect(service.resolveReportingTimezone(undefined, undefined)).toBe('America/New_York');
+    expect(service.resolveReportingTimezone(undefined, 'America/Los_Angeles')).toBe(
+      'America/New_York'
+    );
+
+    const status = service.getServerStatus(null);
+    expect(status.data).toMatchObject({
+      startupDefaults: {
+        preferredTimezone: 'America/New_York',
+        preferredHouseStyle: 'W',
+        weekdayLabels: true,
+      },
+    });
+  });
+
+  it('Given preferred house style and weekday labels, then deterministic defaults apply when the chart did not explicitly request a system', () => {
+    const { service, houseCalc } = makeService({
+      preferredTimezone: 'America/New_York',
+      preferredHouseStyle: 'W',
+      weekdayLabels: true,
+    });
+
+    const houses = service.getHouses(makeNatalChart());
+    const eclipses = service.getNextEclipses();
+
+    expect(houseCalc.calculateHouses).toHaveBeenLastCalledWith(
+      makeNatalChart().julianDay,
+      makeNatalChart().location.latitude,
+      makeNatalChart().location.longitude,
+      'W'
+    );
+    expect((houses.data as any).system).toBe('W');
+    expect((eclipses.data as any).timezone).toBe('America/New_York');
+    expect(eclipses.text).toMatch(/\b(Mon|Tue|Wed|Thu|Fri|Sat|Sun)\b/);
+  });
+
+  it('Given no house system on the chart, then preferred house style is used as the fallback', () => {
+    const { service, houseCalc } = makeService({
+      preferredHouseStyle: 'W',
+    });
+    const natalChart = { ...makeNatalChart(), houseSystem: undefined };
+
+    service.getHouses(natalChart);
+
+    expect(houseCalc.calculateHouses).toHaveBeenLastCalledWith(
+      natalChart.julianDay,
+      natalChart.location.latitude,
+      natalChart.location.longitude,
+      'W'
+    );
+  });
+
+  it('Given no explicit chart house system, then preferred house style overrides the stored default', () => {
+    const { service, houseCalc } = makeService({
+      preferredHouseStyle: 'W',
+    });
+    const natalChart = {
+      ...makeNatalChart(),
+      houseSystem: 'P' as const,
+      requestedHouseSystem: undefined,
+    };
+
+    service.getHouses(natalChart);
+
+    expect(houseCalc.calculateHouses).toHaveBeenLastCalledWith(
+      natalChart.julianDay,
+      natalChart.location.latitude,
+      natalChart.location.longitude,
+      'W'
+    );
+  });
+
+  it('Given an explicit chart house system, then preferred house style does not override it', () => {
+    const { service, houseCalc } = makeService({
+      preferredHouseStyle: 'W',
+    });
+    const natalChart = {
+      ...makeNatalChart(),
+      houseSystem: 'P' as const,
+      requestedHouseSystem: 'P' as const,
+    };
+
+    service.getHouses(natalChart);
+
+    expect(houseCalc.calculateHouses).toHaveBeenLastCalledWith(
+      natalChart.julianDay,
+      natalChart.location.latitude,
+      natalChart.location.longitude,
+      'P'
+    );
+  });
+
+  it('Given a preferred reporting timezone, then rise/set text renders in that timezone', async () => {
+    const { service } = makeService({
+      preferredTimezone: 'America/New_York',
+    });
+
+    const result = await service.getRiseSetTimes(makeNatalChart());
+
+    expect(result.data).toMatchObject({
+      timezone: 'America/Los_Angeles',
+    });
+    expect(result.text).toContain('EDT');
+  });
+
+  it('Given a preferred reporting timezone, then transit exact-time text uses it ahead of natal timezone', () => {
+    const { service } = makeService({
+      preferredTimezone: 'America/New_York',
+    });
+
+    const result = service.getTransits(makeNatalChart());
+
+    expect(result.text).toContain('EDT');
+  });
+
+  it('Given a preferred reporting timezone that crosses midnight, then transit labels use reporting time while payload keeps both zones', () => {
+    const { service } = makeService({
+      preferredTimezone: 'Asia/Tokyo',
+    });
+
+    const result = service.getTransits(makeNatalChart(), {
+      date: '2024-03-26',
+      mode: 'forecast',
+    });
+
+    expect(result.data).toMatchObject({
+      timezone: 'Asia/Tokyo',
+      calculation_timezone: 'America/Los_Angeles',
+      reporting_timezone: 'Asia/Tokyo',
+      window_start: '2024-03-27',
+      window_end: '2024-03-27',
+      forecast: [{ date: '2024-03-27' }],
+    });
+  });
+
+  it('Given an exact transit time, then transit house placement is calculated from that event time', () => {
+    const { service, ephem, houseCalc } = makeService();
+    ephem.dateToJulianDay.mockImplementation((date: Date) => {
+      if (date.toISOString() === '2024-03-27T12:00:00.000Z') {
+        return 9999;
+      }
+      return date.getTime() / 86400000 + 2440587.5;
+    });
+
+    service.getTransits(makeNatalChart(), { mode: 'snapshot' });
+
+    expect(houseCalc.calculateHouses).toHaveBeenCalledWith(
+      9999,
+      makeNatalChart().location.latitude,
+      makeNatalChart().location.longitude,
+      'P'
+    );
+  });
+
+  it('Given an exact transit time, then house assignment uses exact-time longitude instead of sampled longitude', () => {
+    const { service, ephem, transitCalc, houseCalc } = makeService();
+    transitCalc.findTransits.mockReturnValue([
+      {
+        transitingPlanet: 'Moon',
+        natalPlanet: 'Sun',
+        aspect: 'square',
+        orb: 0.1,
+        isApplying: true,
+        exactTimeStatus: 'within_preview',
+        transitLongitude: 99.5,
+        natalLongitude: 10,
+        exactTime: new Date('2024-03-27T12:00:00Z'),
+      },
+    ]);
+    ephem.dateToJulianDay.mockImplementation((date: Date) => {
+      if (date.toISOString() === '2024-03-27T12:00:00.000Z') {
+        return 9999;
+      }
+      return date.getTime() / 86400000 + 2440587.5;
+    });
+    ephem.getPlanetPosition.mockReturnValue(makePlanet('Moon', 100.5));
+    houseCalc.calculateHouses.mockReturnValue({
+      ascendant: 0,
+      mc: 90,
+      cusps: [0, 0, 30, 60, 90, 100, 150, 180, 210, 240, 270, 300, 330],
+      system: 'P' as const,
+    });
+
+    const result = service.getTransits(makeNatalChart(), { mode: 'snapshot' });
+
+    expect((result.data as any).transits[0]).toMatchObject({
+      transitHouse: 5,
+      transitLongitude: 99.5,
+    });
+    expect(ephem.getPlanetPosition).toHaveBeenCalledWith(1, 9999);
+  });
+
   it('Given eclipse availability, then getNextEclipses returns summary or empty-state text', () => {
     const { service, eclipseCalc } = makeService();
     const withOne = service.getNextEclipses('UTC');
@@ -271,6 +888,10 @@ describe('When using AstroService', () => {
     const { service } = makeService();
     expect(() => service.getTransits(makeNatalChart(), { days_ahead: -1 })).toThrow(/days_ahead/);
     expect(() => service.getTransits(makeNatalChart(), { max_orb: -1 })).toThrow(/max_orb/);
+    expect(() => service.getTransits(makeNatalChart(), { mode: 'weekly' as any })).toThrow(/mode/);
+    expect(() =>
+      service.getTransits({ ...makeNatalChart(), julianDay: undefined })
+    ).toThrow(/missing julianDay/i);
     expect(() => service.getHouses({ ...makeNatalChart(), julianDay: undefined })).toThrow(/missing julianDay/i);
   });
 
@@ -320,4 +941,129 @@ describe('When using AstroService', () => {
     expect((result.data as any).eclipses).toHaveLength(2);
     expect(result.text).toContain('Next Lunar Eclipse');
   });
+
+  it('Given date/location inputs, then getRisingSignWindows returns deterministic sign intervals', () => {
+    const { service, houseCalc } = makeService();
+    houseCalc.calculateHouses.mockImplementation((jd: number) => {
+      const dayFraction = ((jd % 1) + 1) % 1;
+      const ascendant = (dayFraction * 360 * 12) % 360;
+      return {
+        ascendant,
+        mc: 204,
+        cusps: [0, 270, 300, 330, 0, 30, 60, 90, 120, 150, 204, 240, 260],
+        system: 'P' as const,
+      };
+    });
+
+    const result = service.getRisingSignWindows({
+      date: '2026-03-28',
+      latitude: 40.7128,
+      longitude: -74.006,
+      timezone: 'America/New_York',
+      mode: 'exact',
+    });
+
+    const windows = (result.data as any).windows;
+    expect((result.data as any)).toMatchObject({
+      date: '2026-03-28',
+      timezone: 'America/New_York',
+      mode: 'exact',
+    });
+    expect(windows.length).toBeGreaterThan(0);
+    expect(windows[0]).toMatchObject({
+      sign: expect.any(String),
+      start: expect.any(String),
+      end: expect.any(String),
+      durationMinutes: expect.any(Number),
+    });
+    expect(windows[0].start).toMatch(/[-+]\d{2}:\d{2}$/);
+    expect(windows[0].start.endsWith('Z')).toBe(false);
+    expect(result.text).toContain('Rising Sign Windows');
+    expect(result.text.toLowerCase()).not.toContain('best');
+  });
+
+  it('Given multiple sign transitions inside one scan bucket, then exact mode emits all boundary windows', () => {
+    const { service, houseCalc } = makeService();
+    const transitions = [
+      Date.parse('2026-03-28T00:10:00Z'),
+      Date.parse('2026-03-28T00:30:00Z'),
+      Date.parse('2026-03-28T00:50:00Z'),
+    ];
+    houseCalc.calculateHouses.mockImplementation((jd: number) => {
+      const date = new Date((jd - 2440587.5) * 86400000);
+      const millis = date.getTime();
+      const signIndex =
+        transitions.filter((transitionMs) => millis >= transitionMs).length % 2 === 0 ? 0 : 1;
+      return {
+        ascendant: signIndex * 30 + 0.1,
+        mc: 204,
+        cusps: [0, 270, 300, 330, 0, 30, 60, 90, 120, 150, 204, 240, 260],
+        system: 'P' as const,
+      };
+    });
+
+    const result = service.getRisingSignWindows({
+      date: '2026-03-28',
+      latitude: 40.7128,
+      longitude: -74.006,
+      timezone: 'UTC',
+      mode: 'exact',
+    });
+
+    const windows = (result.data as any).windows as Array<{ start: string; end: string; sign: string }>;
+    const firstHourWindows = windows.filter((window) => window.start < '2026-03-28T01:00:00+00:00');
+
+    expect(firstHourWindows).toHaveLength(4);
+    expect(firstHourWindows.map((window) => window.sign)).toEqual(['Aries', 'Taurus', 'Aries', 'Taurus']);
+  });
+
+  it('Given invalid rising-sign inputs, then getRisingSignWindows throws clear validation errors', () => {
+    const { service } = makeService();
+
+    expect(() =>
+      service.getRisingSignWindows({
+        date: '2026-03-28',
+        latitude: 95,
+        longitude: -74,
+        timezone: 'America/New_York',
+      })
+    ).toThrow(/Invalid latitude/);
+
+    expect(() =>
+      service.getRisingSignWindows({
+        date: '2026-03-28',
+        latitude: 40,
+        longitude: -190,
+        timezone: 'America/New_York',
+      })
+    ).toThrow(/Invalid longitude/);
+
+    expect(() =>
+      service.getRisingSignWindows({
+        date: '2026/03/28',
+        latitude: 40,
+        longitude: -74,
+        timezone: 'America/New_York',
+      })
+    ).toThrow(/Invalid date format/);
+
+    expect(() =>
+      service.getRisingSignWindows({
+        date: '2026-03-28',
+        latitude: 40,
+        longitude: -74,
+        timezone: 'Nope/Not-A-Timezone',
+      })
+    ).toThrow(/Invalid timezone/);
+
+    expect(() =>
+      service.getRisingSignWindows({
+        date: '2026-03-28',
+        latitude: 40,
+        longitude: -74,
+        timezone: 'UTC',
+        mode: 'fast' as any,
+      })
+    ).toThrow(/Invalid mode/);
+  });
 });