ether-to-astro 1.0.0

package/tests/unit/tool-registry.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createToolSpecIndex, getToolSpec, MCP_TOOL_SPECS } from '../../src/tool-registry.js';
+
+function makeService() {
+  return {
+    setNatalChart: vi.fn(() => ({ data: { ok: true }, text: 'set', chart: { name: 'x' } })),
+    getTransits: vi.fn(() => ({ data: { transits: [] }, text: 'transits' })),
+    getHouses: vi.fn(() => ({ data: { system: 'P' }, text: 'houses' })),
+    getRetrogradePlanets: vi.fn(() => ({ data: { planets: [] }, text: 'retro' })),
+    getRiseSetTimes: vi.fn(async () => ({ data: { times: [] }, text: 'rise' })),
+    getAsteroidPositions: vi.fn(() => ({ data: { positions: [] }, text: 'asteroids' })),
+    getNextEclipses: vi.fn(() => ({ data: { eclipses: [] }, text: 'eclipses' })),
+    getServerStatus: vi.fn(() => ({ data: { ok: true }, text: 'status' })),
+    generateNatalChart: vi.fn(async () => ({ format: 'svg', text: 'natal', svg: '<svg />' })),
+    generateTransitChart: vi.fn(async () => ({ format: 'png', text: 'transit', image: { data: 'abc', mimeType: 'image/png' } })),
+  };
+}
+
+describe('When resolving tool specs from the registry', () => {
+  it('Given the registry map, then specs are indexed and retrievable by name', () => {
+    const index = createToolSpecIndex();
+    expect(index.size).toBe(MCP_TOOL_SPECS.length);
+    expect(getToolSpec('set_natal_chart')?.name).toBe('set_natal_chart');
+  });
+
+  it('Given set_natal_chart execution, then state result includes natal chart', async () => {
+    const spec = getToolSpec('set_natal_chart');
+    expect(spec).toBeDefined();
+    const service = makeService();
+    const result = await spec!.execute(
+      { service: service as any, natalChart: null },
+      {
+        name: 'A',
+        year: 2000,
+        month: 1,
+        day: 1,
+        hour: 1,
+        minute: 1,
+        latitude: 1,
+        longitude: 1,
+        timezone: 'UTC',
+      }
+    );
+    expect(result.kind).toBe('state');
+    if (result.kind === 'state') {
+      expect(result.natalChart).toBeDefined();
+    }
+  });
+
+  it('Given simple state tools, then calls route to matching service methods', async () => {
+    const service = makeService();
+    const ctx = { service: service as any, natalChart: { name: 'chart' } as any };
+    const retro = await getToolSpec('get_retrograde_planets')!.execute(ctx, { timezone: 'UTC' });
+    const status = await getToolSpec('get_server_status')!.execute(ctx, {});
+    expect(retro.kind).toBe('state');
+    expect(status.kind).toBe('state');
+    expect(service.getRetrogradePlanets).toHaveBeenCalledWith('UTC');
+    expect(service.getServerStatus).toHaveBeenCalled();
+  });
+
+  it('Given async state tool handlers, then they resolve to state payloads', async () => {
+    const service = makeService();
+    const ctx = { service: service as any, natalChart: { name: 'chart' } as any };
+    const rise = await getToolSpec('get_rise_set_times')!.execute(ctx, {});
+    const ast = await getToolSpec('get_asteroid_positions')!.execute(ctx, { timezone: 'UTC' });
+    const eclipse = await getToolSpec('get_next_eclipses')!.execute(ctx, { timezone: 'UTC' });
+    expect(rise.kind).toBe('state');
+    expect(ast.kind).toBe('state');
+    expect(eclipse.kind).toBe('state');
+  });
+
+  it('Given natal chart SVG output, then content includes text plus SVG', async () => {
+    const service = makeService();
+    const result = await getToolSpec('generate_natal_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+    expect(result.kind).toBe('content');
+    if (result.kind === 'content') {
+      expect(result.content).toHaveLength(2);
+      expect(result.content[1]).toMatchObject({ type: 'text' });
+    }
+  });
+
+  it('Given transit chart output_path, then content includes text-only save confirmation', async () => {
+    const service = makeService();
+    service.generateTransitChart.mockResolvedValue({
+      format: 'png',
+      text: 'saved',
+      outputPath: '/tmp/out.png',
+    });
+
+    const result = await getToolSpec('generate_transit_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+
+    expect(result.kind).toBe('content');
+    if (result.kind === 'content') {
+      expect(result.content).toHaveLength(1);
+      expect(result.content[0]).toMatchObject({ type: 'text', text: 'saved' });
+    }
+  });
+
+  it('Given transit chart binary image output, then content includes image payload', async () => {
+    const service = makeService();
+    service.generateTransitChart.mockResolvedValue({
+      format: 'png',
+      text: 'transit',
+      image: { data: 'xyz', mimeType: 'image/png' },
+    });
+    const result = await getToolSpec('generate_transit_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+    expect(result.kind).toBe('content');
+    if (result.kind === 'content') {
+      expect(result.content[1]).toMatchObject({ type: 'image', mimeType: 'image/png' });
+    }
+  });
+
+  it('Given natal output_path and transit SVG output, then each branch returns the expected content shape', async () => {
+    const service = makeService();
+    service.generateNatalChart.mockResolvedValue({
+      format: 'png',
+      text: 'saved natal',
+      outputPath: '/tmp/natal.png',
+    });
+    service.generateTransitChart.mockResolvedValue({
+      format: 'svg',
+      text: 'transit svg',
+      svg: '<svg />',
+    });
+
+    const natal = await getToolSpec('generate_natal_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+    const transit = await getToolSpec('generate_transit_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+    expect(natal.kind).toBe('content');
+    expect(transit.kind).toBe('content');
+    if (natal.kind === 'content') {
+      expect(natal.content).toHaveLength(1);
+    }
+    if (transit.kind === 'content') {
+      expect(transit.content).toHaveLength(2);
+    }
+  });
+
+  it('Given natal chart binary image output, then content includes image payload', async () => {
+    const service = makeService();
+    service.generateNatalChart.mockResolvedValue({
+      format: 'webp',
+      text: 'natal image',
+      image: { data: 'img', mimeType: 'image/webp' },
+    });
+    const result = await getToolSpec('generate_natal_chart')!.execute(
+      { service: service as any, natalChart: { name: 'chart' } as any },
+      {}
+    );
+    expect(result.kind).toBe('content');
+    if (result.kind === 'content') {
+      expect(result.content[1]).toMatchObject({ type: 'image', mimeType: 'image/webp' });
+    }
+  });
+
+  it('Given tool metadata, then natal-dependent tools are flagged correctly', () => {
+    const required = new Set(
+      MCP_TOOL_SPECS.filter((s) => s.requiresNatalChart).map((s) => s.name)
+    );
+    expect(required.has('get_transits')).toBe(true);
+    expect(required.has('get_houses')).toBe(true);
+    expect(required.has('get_rise_set_times')).toBe(true);
+    expect(required.has('generate_natal_chart')).toBe(true);
+    expect(required.has('generate_transit_chart')).toBe(true);
+  });
+
+  it('Given chart tools return no payload, then execution throws explicit errors', async () => {
+    const service = makeService();
+    service.generateNatalChart.mockResolvedValue({ format: 'svg', text: 'oops' });
+    await expect(
+      getToolSpec('generate_natal_chart')!.execute(
+        { service: service as any, natalChart: { name: 'chart' } as any },
+        {}
+      )
+    ).rejects.toThrow(/no payload/i);
+    service.generateTransitChart.mockResolvedValue({ format: 'svg', text: 'oops' });
+    await expect(
+      getToolSpec('generate_transit_chart')!.execute(
+        { service: service as any, natalChart: { name: 'chart' } as any },
+        {}
+      )
+    ).rejects.toThrow(/no payload/i);
+  });
+
+  it('Given timezone arguments and natal context, then non-natal tools apply timezone precedence correctly', async () => {
+    const service = makeService();
+    const retro = getToolSpec('get_retrograde_planets')!;
+    const asteroids = getToolSpec('get_asteroid_positions')!;
+    const eclipses = getToolSpec('get_next_eclipses')!;
+
+    await retro.execute(
+      { service: service as any, natalChart: { location: { timezone: 'Asia/Tokyo' } } as any },
+      {}
+    );
+    await asteroids.execute(
+      { service: service as any, natalChart: null },
+      {}
+    );
+    await eclipses.execute(
+      { service: service as any, natalChart: { location: { timezone: 'America/New_York' } } as any },
+      { timezone: 'UTC' }
+    );
+
+    expect(service.getRetrogradePlanets).toHaveBeenCalledWith('Asia/Tokyo');
+    expect(service.getAsteroidPositions).toHaveBeenCalledWith('UTC');
+    expect(service.getNextEclipses).toHaveBeenCalledWith('UTC');
+  });
+});

package/tests/unit/tool-result.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  failure,
+  mapSweError,
+  mcpError,
+  mcpResult,
+  success,
+  type ToolIssue,
+} from '../../src/tool-result.js';
+
+describe('When building tool result envelopes', () => {
+  it('Given success and failure inputs, then wrapper helpers return the expected discriminated shapes', () => {
+    const warning: ToolIssue = { code: 'INVALID_INPUT', message: 'warn', retryable: true };
+    expect(success({ ok: 1 })).toEqual({ ok: true, data: { ok: 1 } });
+    expect(success({ ok: 1 }, [warning])).toEqual({ ok: true, data: { ok: 1 }, warnings: [warning] });
+    expect(failure(warning)).toEqual({ ok: false, error: warning });
+  });
+
+  it('Given a successful MCP result with optional warnings, then content envelope includes expected fields', () => {
+    const withoutWarnings = mcpResult({ x: 1 }, 'ok');
+    const withWarnings = mcpResult({ x: 1 }, 'ok', [
+      { code: 'INVALID_INPUT', message: 'warn', retryable: true },
+    ]);
+    expect(withoutWarnings.content).toHaveLength(2);
+    expect(withWarnings.content).toHaveLength(2);
+    expect(withWarnings.content[0].text).toContain('"warnings"');
+  });
+
+  it('Given an MCP error, then envelope marks isError and includes structured payload', () => {
+    const result = mcpError({ code: 'INTERNAL_ERROR', message: 'boom', retryable: false });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('"ok": false');
+    expect(result.content[0].text).toContain('"INTERNAL_ERROR"');
+  });
+
+  it('Given sweph initialization and generic errors, then mapSweError returns correct issue codes/details', () => {
+    const init = mapSweError('calc', new Error('not initialized'));
+    expect(init.code).toBe('EPHEMERIS_NOT_INITIALIZED');
+    expect(init.details).toBeUndefined();
+
+    const generic = mapSweError('houses', new Error('bad value'), { lat: 1 });
+    expect(generic.code).toBe('EPHEMERIS_COMPUTE_FAILED');
+    expect(generic.details).toMatchObject({ lat: 1, rawMessage: 'bad value' });
+  });
+});

package/tests/unit/transit-correctness.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { TransitCalculator } from '../../src/transits.js';
+import { EphemerisCalculator } from '../../src/ephemeris.js';
+import { PLANETS, type PlanetPosition } from '../../src/types.js';
+
+describe('Transit calculation correctness', () => {
+  let ephem: EphemerisCalculator;
+  let transitCalc: TransitCalculator;
+
+  beforeAll(async () => {
+    ephem = new EphemerisCalculator();
+    await ephem.init();
+    transitCalc = new TransitCalculator(ephem);
+  });
+
+  describe('Dual-target exact time calculation', () => {
+    it('should find exact times for both sides of square aspect', () => {
+      const currentDate = new Date(Date.UTC(2024, 2, 26, 12, 0));
+      const currentJD = ephem.dateToJulianDay(currentDate);
+      const mars = ephem.getAllPlanets(currentJD, [PLANETS.MARS])[0];
+      const natalPlanets: PlanetPosition[] = [
+        { ...mars, planetId: PLANETS.VENUS, planet: 'Venus', longitude: (mars.longitude + 90) % 360 },
+      ];
+      const transits = transitCalc.findTransits([mars], natalPlanets, currentJD);
+      const squares = transits.filter(t => t.aspect === 'square');
+      expect(squares.length).toBeGreaterThan(0);
+      expect(squares[0].aspect).toBe('square');
+      expect(squares[0].orb).toBeLessThanOrEqual(7);
+    });
+
+    it('should search both target longitudes for trine', () => {
+      const currentDate = new Date(Date.UTC(2024, 2, 26, 12, 0));
+      const currentJD = ephem.dateToJulianDay(currentDate);
+      const jupiter = ephem.getAllPlanets(currentJD, [PLANETS.JUPITER])[0];
+      const natalPlanets: PlanetPosition[] = [
+        { ...jupiter, planetId: PLANETS.SUN, planet: 'Sun', longitude: (jupiter.longitude + 120) % 360 },
+      ];
+      const transits = transitCalc.findTransits([jupiter], natalPlanets, currentJD);
+      const trines = transits.filter(t => t.aspect === 'trine');
+      expect(trines.length).toBeGreaterThan(0);
+      expect(trines[0].aspect).toBe('trine');
+      expect(trines[0].orb).toBeLessThanOrEqual(7);
+    });
+  });
+
+  describe('Dynamic search window for slow movers', () => {
+    it('should use wider search window for slow-moving planets', () => {
+      // This is tested by checking if slow-mover exact times are found
+      const currentDate = new Date(Date.UTC(2024, 2, 26, 12, 0));
+      const currentJD = ephem.dateToJulianDay(currentDate);
+      const saturn = ephem.getAllPlanets(currentJD, [PLANETS.SATURN])[0];
+      const natalPlanets: PlanetPosition[] = [
+        { ...saturn, planetId: PLANETS.SUN, planet: 'Sun', longitude: (saturn.longitude + 1) % 360 },
+      ];
+
+      const transits = transitCalc.findTransits([saturn], natalPlanets, currentJD);
+      const closeTransits = transits.filter(t => t.orb < 2);
+      expect(closeTransits.length).toBeGreaterThan(0);
+      closeTransits.forEach((t) => {
+        expect(t.exactTimeStatus).toBeDefined();
+      });
+    });
+  });
+
+  describe('Unknown planet handling', () => {
+    it('should return valid transit objects for supported non-classical bodies', () => {
+      const currentDate = new Date(Date.UTC(2024, 2, 26, 12, 0));
+      const currentJD = ephem.dateToJulianDay(currentDate);
+      const chiron = ephem.getAllPlanets(currentJD, [PLANETS.CHIRON])[0];
+      const natalPlanets: PlanetPosition[] = [
+        { ...chiron, planetId: PLANETS.SUN, planet: 'Sun', longitude: chiron.longitude },
+      ];
+      const transits = transitCalc.findTransits([chiron], natalPlanets, currentJD);
+      expect(transits.length).toBeGreaterThan(0);
+      expect(transits[0].transitingPlanet).toBe('Chiron');
+    });
+  });
+});

package/tests/unit/transits.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { TransitCalculator } from '../../src/transits.js';
+import { EphemerisCalculator } from '../../src/ephemeris.js';
+import { PLANETS, ASPECTS } from '../../src/types.js';
+import { bowenYangChart } from '../fixtures/bowen-yang-chart.js';
+import { FIXED_TEST_DATE } from '../setup.js';
+
+describe('When an AI asks "What transits is Bowen experiencing today?"', () => {
+  let ephem: EphemerisCalculator;
+  let transitCalc: TransitCalculator;
+
+  beforeAll(async () => {
+    ephem = new EphemerisCalculator();
+    await ephem.init();
+    transitCalc = new TransitCalculator(ephem);
+  });
+
+  describe('Given Bowen Yang\'s natal chart', () => {
+    it('should find transits between current planets and natal planets', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const transits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+
+      expect(Array.isArray(transits)).toBe(true);
+      expect(transits.length).toBeGreaterThan(0);
+      transits.forEach(transit => {
+        expect(typeof transit.transitingPlanet).toBe('string');
+        expect(typeof transit.natalPlanet).toBe('string');
+        expect(typeof transit.aspect).toBe('string');
+        expect(transit.orb).toBeGreaterThanOrEqual(0);
+        expect(typeof transit.isApplying).toBe('boolean');
+      });
+    });
+
+    it('should calculate applying vs separating aspects correctly', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const transits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+
+      transits.forEach(transit => {
+        expect(typeof transit.isApplying).toBe('boolean');
+      });
+    });
+
+    it('should respect aspect orbs from ASPECTS configuration', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const transits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+
+      transits.forEach(transit => {
+        const aspectConfig = ASPECTS.find(a => a.name === transit.aspect);
+        expect(aspectConfig).toBeDefined();
+        expect(transit.orb).toBeLessThanOrEqual(aspectConfig!.orb);
+      });
+    });
+  });
+
+  describe('When filtering for upcoming transits', () => {
+    it('should find transits approaching within 2 degrees', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const allTransits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+      const upcomingTransits = allTransits.filter(t => t.orb <= 2 && t.isApplying);
+
+      upcomingTransits.forEach(transit => {
+        expect(transit.orb).toBeLessThanOrEqual(2);
+        expect(transit.isApplying).toBe(true);
+      });
+    });
+  });
+
+  describe('When handling Moon transits (fast-moving planet)', () => {
+    it('should find Moon transits to natal planets', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const moonPosition = ephem.getAllPlanets(currentJD, [PLANETS.MOON]);
+      const natalPlanets = moonPosition.map((moon) => ({
+        ...moon,
+        planet: 'Sun' as const,
+        planetId: PLANETS.SUN,
+      }));
+
+      const transits = transitCalc.findTransits(moonPosition, natalPlanets, currentJD);
+
+      expect(transits.length).toBeGreaterThan(0);
+      
+      transits.forEach(transit => {
+        expect(transit.transitingPlanet).toBe('Moon');
+      });
+    });
+  });
+
+  describe('When handling outer planet transits (slow-moving planets)', () => {
+    it('should find outer planet transits with longer-lasting effects', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const outerPlanets = ephem.getAllPlanets(currentJD, [
+        PLANETS.JUPITER,
+        PLANETS.SATURN,
+        PLANETS.URANUS,
+        PLANETS.NEPTUNE,
+        PLANETS.PLUTO
+      ]);
+
+      const transits = transitCalc.findTransits(outerPlanets, natalPlanets, currentJD);
+
+      transits.forEach(transit => {
+        expect(['Jupiter', 'Saturn', 'Uranus', 'Neptune', 'Pluto']).toContain(transit.transitingPlanet);
+      });
+    });
+  });
+
+  describe('When calculating exact transit times', () => {
+    it('should calculate when a transit becomes exact (0° orb)', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const transits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+      
+      // Filter for close transits that might have exact times
+      const closeTransits = transits.filter(t => t.orb < 2);
+      expect(closeTransits.length).toBeGreaterThan(0);
+      closeTransits.forEach(transit => {
+        expect(transit.exactTime === undefined || transit.exactTime instanceof Date).toBe(true);
+      });
+    });
+  });
+
+  describe('When handling edge cases', () => {
+    it('should handle transits at zodiac boundaries (0° Aries, etc.)', () => {
+      // Create a scenario where planet is at 359° and another at 1°
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+      
+      // This tests the angle calculation wrapping logic
+      const angle = ephem.calculateAspectAngle(359, 1);
+      expect(angle).toBe(2);
+    });
+
+    it('should handle retrograde planets correctly', () => {
+      const birthDate = new Date(Date.UTC(
+        bowenYangChart.birthDate.year,
+        bowenYangChart.birthDate.month - 1,
+        bowenYangChart.birthDate.day,
+        bowenYangChart.birthDate.hour,
+        bowenYangChart.birthDate.minute
+      ));
+      const birthJD = ephem.dateToJulianDay(birthDate);
+      const currentJD = ephem.dateToJulianDay(FIXED_TEST_DATE);
+
+      const natalPlanets = ephem.getAllPlanets(birthJD, Object.values(PLANETS));
+      const transitingPlanets = ephem.getAllPlanets(currentJD, Object.values(PLANETS));
+
+      const transits = transitCalc.findTransits(transitingPlanets, natalPlanets, currentJD);
+
+      // Retrograde planets should still form transits
+      const retrogradeTransits = transits.filter(t => {
+        const planet = transitingPlanets.find(p => p.planet === t.transitingPlanet);
+        return planet && planet.speed < 0;
+      });
+
+      // Retrograde transits should be separating (moving backward)
+      retrogradeTransits.forEach(transit => {
+        expect(typeof transit.isApplying).toBe('boolean');
+      });
+    });
+  });
+});

package/tests/validation/README.md

@@ -0,0 +1,32 @@
+# Astro Validation Harness
+
+Run the core harness:
+
+```bash
+npm run validate:astro
+```
+
+Run with optional Astrolog parity:
+
+```bash
+VALIDATE_WITH_ASTROLOG=1 ASTROLOG_BIN=astrolog npm run validate:astro
+```
+
+Notes:
+
+- Core validation requires only Node + this repo.
+- Astrolog checks are optional and auto-skipped unless enabled and available.
+- Astrolog parity covers a curated 25-fixture corpus (positions, houses, transit snapshots, and edge UTC normalization cases).
+- Dense-scan root oracle is independent from production `findExactTransitTimes()`.
+- Hard failures fail the test run.
+- Soft mismatches are logged as warnings.
+- A machine-readable report is written to `/tmp/astro-validation-report.json`.
+- Rise/set and eclipse sections are capability/smoke checks in this harness (exact parity references are not yet externalized there).
+- Astrolog house parity treats Whole Sign ASC/MC cusp proxies as non-comparable; Whole Sign checks focus on cusp parity, while ASC/MC proxy warnings are reserved for non-Whole-Sign systems.
+
+Tolerance summary:
+
+- Position parity (same engine): `0.0001°` for longitude/latitude/speed
+- Houses: `0.01°`
+- Exact roots: preferred `<=2 min`, hard fail `>10 min`
+- Rise/set and eclipse times (same engine references): `<=1 min`