ether-to-astro 1.2.0 → 1.3.0

package/tests/unit/rising-sign-windows.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { compareRisingSignModePrecision } from '../validation/compare/rising-sign-windows.js';
+import type { InternalValidationAdapter } from '../validation/adapters/internal.js';
+import type {
+  NormalizedRisingSignWindowResult,
+  RisingSignModeComparisonFixture,
+} from '../validation/utils/fixtureTypes.js';
+import { ValidationReport } from '../validation/utils/report.js';
+
+describe('When comparing rising-sign window mode precision', () => {
+  it('keeps checking exact precision when approximate skips intermediate exact signs', () => {
+    const fixture: RisingSignModeComparisonFixture = {
+      name: 'coarse approximate subsequence still checks exact boundary precision',
+      baseInput: {
+        date: '2026-03-28',
+        latitude: -65,
+        longitude: -180,
+        timezone: 'America/New_York',
+      },
+    };
+    const approximate: NormalizedRisingSignWindowResult = {
+      date: fixture.baseInput.date,
+      timezone: fixture.baseInput.timezone,
+      mode: 'approximate',
+      windows: [
+        {
+          sign: 'Cancer',
+          start: '2026-03-28T00:00:00.000Z',
+          end: '2026-03-28T02:00:00.000Z',
+          durationMs: 2 * 60 * 60 * 1000,
+        },
+        {
+          sign: 'Libra',
+          start: '2026-03-28T02:00:00.000Z',
+          end: '2026-03-28T06:00:00.000Z',
+          durationMs: 4 * 60 * 60 * 1000,
+        },
+      ],
+    };
+    const exact: NormalizedRisingSignWindowResult = {
+      date: fixture.baseInput.date,
+      timezone: fixture.baseInput.timezone,
+      mode: 'exact',
+      windows: [
+        {
+          sign: 'Cancer',
+          start: '2026-03-28T00:00:00.000Z',
+          end: '2026-03-28T01:30:00.000Z',
+          durationMs: 90 * 60 * 1000,
+        },
+        {
+          sign: 'Leo',
+          start: '2026-03-28T01:30:00.000Z',
+          end: '2026-03-28T01:40:00.000Z',
+          durationMs: 10 * 60 * 1000,
+        },
+        {
+          sign: 'Virgo',
+          start: '2026-03-28T01:40:00.000Z',
+          end: '2026-03-28T01:50:00.000Z',
+          durationMs: 10 * 60 * 1000,
+        },
+        {
+          sign: 'Libra',
+          start: '2026-03-28T01:50:00.000Z',
+          end: '2026-03-28T06:00:00.000Z',
+          durationMs: 250 * 60 * 1000,
+        },
+      ],
+    };
+    const adapter = {
+      getAscendantSignAt(isoUtc: string): string {
+        return isoUtc < '2026-03-28T01:55:00.000Z' ? 'Cancer' : 'Leo';
+      },
+    } as InternalValidationAdapter;
+    const report = new ValidationReport();
+
+    compareRisingSignModePrecision(fixture, approximate, exact, adapter, report);
+
+    expect(report.hardFailures).toHaveLength(2);
+    expect(report.hardFailures[0]?.message).toBe(
+      'Exact mode inserted intermediate sign windows where approximate mode reported a single boundary'
+    );
+    expect(report.hardFailures[1]?.message).toBe(
+      'Exact mode boundary was less precise than approximate mode'
+    );
+    expect(report.hardFailures[1]?.details).toMatchObject({
+      actualTransitionIsoUtc: '2026-03-28T01:55:00.000Z',
+      approximateBoundary: '2026-03-28T02:00:00.000Z',
+      exactBoundary: '2026-03-28T01:30:00.000Z',
+    });
+  });
+});

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

@@ -81,6 +81,17 @@ describe('When resolving tool specs from the registry', () => {
     });
   });
 
+  it('Given get_transits schema, then include_mundane description matches shipped mundane contract', () => {
+    const spec = getToolSpec('get_transits');
+    expect(spec).toBeDefined();
+    const includeMundane = (spec!.inputSchema as any).properties.include_mundane.description as string;
+
+    expect(includeMundane).toContain('planetary positions');
+    expect(includeMundane).toContain('mundane aspects');
+    expect(includeMundane).toContain('weather');
+    expect(includeMundane).toContain('mundane.days');
+  });
+
   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 };

package/tests/validation/README.md

@@ -16,14 +16,28 @@ Notes:
 
 - Core validation requires only Node + this repo.
 - Astrolog checks are optional and auto-skipped unless enabled and available.
+- Astrolog parity is the repo's optional curated external-oracle lane.
 - 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()`.
+- The harness now validates both engine-level math and deterministic `AstroService` behavior.
 - 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.
 
+Service-layer coverage now includes:
+
+- Electional context invariants: sect classification, near-horizon warnings, house fallback warnings, and optional-field toggles.
+- Rising-sign window invariants: full local-day coverage, DST-transition serialization, deterministic repeats, and exact-vs-approximate boundary precision.
+- Service-level transit serialization: enriched placement fields, explicit calculation/reporting timezones, forecast grouping, and sign-boundary carry behavior.
+
+Property testing is intentionally separate from this harness:
+
+- `npm run test:property` runs generated `fast-check` invariants.
+- Property tests do not use Astrolog parity.
+- Astrolog remains a named, curated, opt-in oracle lane for credibility and explainable golden-case comparisons.
+
 Tolerance summary:
 
 - Position parity (same engine): `0.0001°` for longitude/latitude/speed

package/tests/validation/adapters/internal.ts

@@ -1,16 +1,37 @@
+import { parseDateOnlyInput } from '../../../src/astro-service/date-input.js';
+import type {
+  GetElectionalContextInput,
+  GetRisingSignWindowsInput,
+  GetTransitsInput,
+} from '../../../src/astro-service/service-types.js';
+import { getSignAndDegree, normalizeLongitude } from '../../../src/astro-service/shared.js';
+import { AstroService } from '../../../src/astro-service.js';
 import { EclipseCalculator } from '../../../src/eclipses.js';
+import type { McpStartupDefaults } from '../../../src/entrypoint.js';
 import { EphemerisCalculator } from '../../../src/ephemeris.js';
 import { HouseCalculator } from '../../../src/houses.js';
 import { RiseSetCalculator } from '../../../src/riseset.js';
+import { localToUTC, utcToLocal } from '../../../src/time-utils.js';
 import { TransitCalculator } from '../../../src/transits.js';
-import type { PlanetPosition, Transit } from '../../../src/types.js';
+import {
+  type NatalChart,
+  PLANETS,
+  type PlanetPosition,
+  type Transit,
+  ZODIAC_SIGNS,
+} from '../../../src/types.js';
 import type {
   NormalizedBody,
   NormalizedEclipse,
+  NormalizedElectionalContext,
   NormalizedHouseResult,
   NormalizedRiseSet,
+  NormalizedRisingSignWindowResult,
   NormalizedRoot,
+  NormalizedServiceTransit,
+  NormalizedServiceTransitResult,
   NormalizedTransit,
+  ServiceTransitNatalFixture,
 } from '../utils/fixtureTypes.js';
 
 export class InternalValidationAdapter {
@@ -19,19 +40,21 @@ export class InternalValidationAdapter {
   readonly transitCalc: TransitCalculator;
   readonly riseSetCalc: RiseSetCalculator;
   readonly eclipseCalc: EclipseCalculator;
+  private readonly validationNow: Date;
 
-  private constructor(ephem: EphemerisCalculator) {
+  private constructor(ephem: EphemerisCalculator, validationNow: Date) {
     this.ephem = ephem;
     this.houseCalc = new HouseCalculator(ephem);
     this.transitCalc = new TransitCalculator(ephem);
     this.riseSetCalc = new RiseSetCalculator(ephem);
     this.eclipseCalc = new EclipseCalculator(ephem);
+    this.validationNow = validationNow;
   }
 
-  static async create(): Promise<InternalValidationAdapter> {
+  static async create(nowIsoUtc = '2024-03-26T12:00:00Z'): Promise<InternalValidationAdapter> {
     const ephem = new EphemerisCalculator();
     await ephem.init();
-    return new InternalValidationAdapter(ephem);
+    return new InternalValidationAdapter(ephem, new Date(nowIsoUtc));
   }
 
   getPositions(isoUtc: string, planetIds: number[]): NormalizedBody[] {
@@ -139,6 +162,126 @@ export class InternalValidationAdapter {
     };
   }
 
+  getElectionalContext(input: GetElectionalContextInput): NormalizedElectionalContext {
+    const service = this.createService();
+    const result = service.getElectionalContext(input);
+    const data = result.data as {
+      input: { house_system: string; instant_utc: string };
+      sect: {
+        classification: 'day' | 'night';
+        is_day_chart: boolean;
+        sun_altitude_degrees: number;
+      };
+      moon: { applying_aspects?: unknown[] };
+      applying_aspects?: unknown[];
+      ruler_basics?: unknown;
+      meta: { warnings: string[] };
+    };
+
+    const instantUtc = new Date(data.input.instant_utc);
+    const jdUt = this.ephem.dateToJulianDay(instantUtc);
+    const sun = this.ephem.getPlanetPosition(PLANETS.SUN, jdUt);
+    const rawSunAltitudeDegrees = this.ephem.getHorizontalCoordinates(
+      jdUt,
+      sun,
+      input.longitude,
+      input.latitude
+    ).trueAltitude;
+
+    return {
+      houseSystem: data.input.house_system,
+      classification: data.sect.classification,
+      isDayChart: data.sect.is_day_chart,
+      sunAltitudeDegrees: data.sect.sun_altitude_degrees,
+      rawSunAltitudeDegrees,
+      sunAltitudeDisplaysZero:
+        data.sect.sun_altitude_degrees === 0 || Object.is(data.sect.sun_altitude_degrees, -0),
+      warnings: data.meta.warnings,
+      hasApplyingAspects: Array.isArray(data.applying_aspects),
+      applyingAspectCount: data.applying_aspects?.length ?? 0,
+      hasMoonApplyingAspects: Array.isArray(data.moon.applying_aspects),
+      moonApplyingAspectCount: data.moon.applying_aspects?.length ?? 0,
+      hasRulerBasics: data.ruler_basics !== undefined,
+    };
+  }
+
+  getRisingSignWindows(input: GetRisingSignWindowsInput): NormalizedRisingSignWindowResult {
+    const service = this.createService();
+    const result = service.getRisingSignWindows(input);
+    const data = result.data as {
+      date: string;
+      timezone: string;
+      mode: 'approximate' | 'exact';
+      windows: Array<{
+        sign: string;
+        start: string;
+        end: string;
+        durationMs: number;
+      }>;
+    };
+
+    return {
+      date: data.date,
+      timezone: data.timezone,
+      mode: data.mode,
+      windows: data.windows.map((window) => ({ ...window })),
+    };
+  }
+
+  getServiceTransits(input: {
+    natalChart: ServiceTransitNatalFixture;
+    transitInput: GetTransitsInput;
+    startupDefaults?: McpStartupDefaults;
+  }): NormalizedServiceTransitResult {
+    const service = this.createService(input.startupDefaults);
+    const targetDate = this.resolveTransitTargetDate(
+      input.transitInput.date,
+      input.natalChart.timezone
+    );
+    const natalChart = this.buildNatalChartFromOffsets(input.natalChart, targetDate);
+    const result = service.getTransits(natalChart, input.transitInput);
+    const data = result.data as {
+      mode?: 'snapshot' | 'best_hit' | 'forecast';
+      mode_source?: 'legacy_default' | 'explicit';
+      date?: string;
+      timezone: string;
+      calculation_timezone?: string;
+      reporting_timezone?: string;
+      days_ahead?: number;
+      window_start?: string;
+      window_end?: string;
+      transits?: Array<Record<string, unknown>>;
+      forecast?: Array<{
+        date: string;
+        transits: Array<Record<string, unknown>>;
+      }>;
+    };
+
+    return {
+      mode: data.mode,
+      modeSource: data.mode_source,
+      date: data.date,
+      timezone: data.timezone,
+      calculationTimezone: data.calculation_timezone,
+      reportingTimezone: data.reporting_timezone,
+      daysAhead: data.days_ahead,
+      windowStart: data.window_start,
+      windowEnd: data.window_end,
+      transits: data.transits?.map((transit) => this.normalizeServiceTransit(transit)),
+      forecast: data.forecast?.map((day) => ({
+        date: day.date,
+        transits: day.transits.map((transit) => this.normalizeServiceTransit(transit)),
+      })),
+    };
+  }
+
+  getAscendantSignAt(isoUtc: string, latitude: number, longitude: number): string {
+    const jd = this.ephem.dateToJulianDay(new Date(isoUtc));
+    const houses = this.houseCalc.calculateHouses(jd, latitude, longitude, 'P');
+    const ascendant = normalizeLongitude(houses.ascendant);
+    return ZODIAC_SIGNS[Math.floor(ascendant / 30)];
+  }
+
   canComputeRiseSet(): boolean {
     try {
       const probeJd = this.ephem.dateToJulianDay(new Date('2024-03-26T12:00:00Z'));
@@ -181,4 +324,91 @@ export class InternalValidationAdapter {
       isApplying: t.isApplying,
     };
   }
+
+  private createService(startupDefaults: McpStartupDefaults = {}): AstroService {
+    return new AstroService({
+      ephem: this.ephem,
+      transitCalc: this.transitCalc,
+      houseCalc: this.houseCalc,
+      riseSetCalc: this.riseSetCalc,
+      eclipseCalc: this.eclipseCalc,
+      mcpStartupDefaults: startupDefaults,
+      now: () => new Date(this.validationNow.getTime()),
+    });
+  }
+
+  private resolveTransitTargetDate(dateStr: string | undefined, calculationTimezone: string): Date {
+    if (dateStr) {
+      return localToUTC(parseDateOnlyInput(dateStr), calculationTimezone);
+    }
+
+    const localNow = utcToLocal(this.validationNow, calculationTimezone);
+    return localToUTC({ ...localNow, hour: 12, minute: 0, second: 0 }, calculationTimezone);
+  }
+
+  private buildNatalChartFromOffsets(
+    fixture: ServiceTransitNatalFixture,
+    targetDate: Date
+  ): NatalChart {
+    const targetJulianDay = this.ephem.dateToJulianDay(targetDate);
+    const birthInstant = new Date(fixture.julianDayIsoUtc);
+    const birthDate = utcToLocal(birthInstant, fixture.timezone);
+    const utcBirthDate = utcToLocal(birthInstant, 'UTC');
+
+    const planets = fixture.planetOffsets.map(
+      ({ transitingPlanetId, natalPlanetId, natalOffsetDegrees }) => {
+        const transiting = this.ephem.getPlanetPosition(transitingPlanetId, targetJulianDay);
+        const natalBase = this.ephem.getPlanetPosition(natalPlanetId, targetJulianDay);
+        const longitude = (transiting.longitude + natalOffsetDegrees + 360) % 360;
+        const placement = getSignAndDegree(longitude);
+
+        return {
+          ...natalBase,
+          planetId: natalPlanetId,
+          longitude,
+          sign: placement.sign,
+          degree: placement.degree,
+        };
+      }
+    );
+
+    return {
+      name: fixture.name,
+      birthDate,
+      location: {
+        latitude: fixture.latitude,
+        longitude: fixture.longitude,
+        timezone: fixture.timezone,
+      },
+      planets,
+      julianDay: this.ephem.dateToJulianDay(birthInstant),
+      houseSystem: fixture.houseSystem ?? 'P',
+      requestedHouseSystem: fixture.houseSystem,
+      utcDateTime: utcBirthDate,
+    };
+  }
+
+  private normalizeServiceTransit(transit: Record<string, unknown>): NormalizedServiceTransit {
+    return {
+      transitingPlanet: String(transit.transitingPlanet),
+      natalPlanet: String(transit.natalPlanet),
+      aspect: String(transit.aspect),
+      orb: Number(transit.orb),
+      exactTime: typeof transit.exactTime === 'string' ? transit.exactTime : undefined,
+      exactTimeStatus:
+        transit.exactTimeStatus === 'within_preview' ||
+        transit.exactTimeStatus === 'outside_preview' ||
+        transit.exactTimeStatus === 'not_found' ||
+        transit.exactTimeStatus === 'unsupported_body'
+          ? transit.exactTimeStatus
+          : undefined,
+      isApplying: Boolean(transit.isApplying),
+      transitSign: typeof transit.transitSign === 'string' ? transit.transitSign : undefined,
+      transitDegree: typeof transit.transitDegree === 'number' ? transit.transitDegree : undefined,
+      transitHouse: typeof transit.transitHouse === 'number' ? transit.transitHouse : undefined,
+      natalSign: typeof transit.natalSign === 'string' ? transit.natalSign : undefined,
+      natalDegree: typeof transit.natalDegree === 'number' ? transit.natalDegree : undefined,
+      natalHouse: typeof transit.natalHouse === 'number' ? transit.natalHouse : undefined,
+    };
+  }
 }

package/tests/validation/compare/electional.ts

@@ -0,0 +1,151 @@
+import type { ElectionalFixture, NormalizedElectionalContext } from '../utils/fixtureTypes.js';
+import type { ValidationReport } from '../utils/report.js';
+
+function matchesRawAltitudeSign(
+  value: number,
+  expected: 'positive' | 'negative' | 'zero'
+): boolean {
+  if (expected === 'zero') {
+    return Math.abs(value) < 1e-9;
+  }
+  return expected === 'positive' ? value > 0 : value < 0;
+}
+
+export function compareElectionalContext(
+  fixture: ElectionalFixture,
+  actual: NormalizedElectionalContext,
+  report: ValidationReport
+): void {
+  const { expected } = fixture;
+
+  if (actual.classification !== expected.classification) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.classification,
+      actual: actual.classification,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Sect classification mismatch',
+      details: actual,
+    });
+  }
+
+  if (actual.isDayChart !== expected.isDayChart) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.isDayChart,
+      actual: actual.isDayChart,
+      delta: null,
+      tolerance: 'exact',
+      message: 'is_day_chart mismatch',
+      details: actual,
+    });
+  }
+
+  if (expected.houseSystem && actual.houseSystem !== expected.houseSystem) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.houseSystem,
+      actual: actual.houseSystem,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Resolved house system mismatch',
+      details: actual,
+    });
+  }
+
+  if (
+    expected.rawSunAltitudeSign &&
+    !matchesRawAltitudeSign(actual.rawSunAltitudeDegrees, expected.rawSunAltitudeSign)
+  ) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.rawSunAltitudeSign,
+      actual: actual.rawSunAltitudeDegrees,
+      delta: null,
+      tolerance: 'sign only',
+      message: 'Raw Sun altitude sign mismatch',
+      details: actual,
+    });
+  }
+
+  if (
+    expected.sunAltitudeDisplaysZero !== undefined &&
+    actual.sunAltitudeDisplaysZero !== expected.sunAltitudeDisplaysZero
+  ) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.sunAltitudeDisplaysZero,
+      actual: actual.sunAltitudeDisplaysZero,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Rounded Sun altitude zero-display expectation mismatch',
+      details: actual,
+    });
+  }
+
+  for (const warning of expected.warningsContain ?? []) {
+    if (!actual.warnings.includes(warning)) {
+      report.addHard({
+        fixture: fixture.name,
+        subsystem: 'electional',
+        expected: warning,
+        actual: actual.warnings,
+        delta: null,
+        tolerance: 'contains',
+        message: 'Expected electional warning was not emitted',
+        details: actual,
+      });
+    }
+  }
+
+  if (
+    expected.hasApplyingAspects !== undefined &&
+    actual.hasApplyingAspects !== expected.hasApplyingAspects
+  ) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.hasApplyingAspects,
+      actual: actual.hasApplyingAspects,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Top-level applying-aspect presence mismatch',
+      details: actual,
+    });
+  }
+
+  if (
+    expected.hasMoonApplyingAspects !== undefined &&
+    actual.hasMoonApplyingAspects !== expected.hasMoonApplyingAspects
+  ) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.hasMoonApplyingAspects,
+      actual: actual.hasMoonApplyingAspects,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Moon applying-aspect presence mismatch',
+      details: actual,
+    });
+  }
+
+  if (expected.hasRulerBasics !== undefined && actual.hasRulerBasics !== expected.hasRulerBasics) {
+    report.addHard({
+      fixture: fixture.name,
+      subsystem: 'electional',
+      expected: expected.hasRulerBasics,
+      actual: actual.hasRulerBasics,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Ruler-basics presence mismatch',
+      details: actual,
+    });
+  }
+}