ether-to-astro 1.2.0 → 1.3.0

package/src/tool-registry.ts

@@ -218,7 +218,7 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
         include_mundane: {
           type: 'boolean',
           description:
-            'Include current planetary positions (not transits to natal chart). Defaults to false.',
+            'Include deterministic mundane baseline data for the requested window. Output includes planetary positions, transit-to-transit mundane aspects, and non-narrative weather grouping metadata; forecast windows also include per-day mundane.days entries. Defaults to false.',
         },
         days_ahead: {
           type: 'number',

package/tests/README.md

@@ -13,6 +13,7 @@ tests/
 │   ├── ephemeris/transits/*   # Core astrology math and solver behavior
 │   ├── riseset/eclipses/*     # Event calculators and edge flags
 │   └── charts/houses/*        # Rendering and house-system behavior
+├── property/                  # `fast-check` invariant coverage and shrinkable counterexamples
 ├── helpers/                   # Reusable test helpers/builders
 ├── fixtures/                  # Test data and fixtures
 │   ├── bowen-yang-chart.ts    # Bowen Yang's birth chart
@@ -32,6 +33,9 @@ npm test
 # Run tests with coverage
 npm run test:coverage
 
+# Run property tests
+npm run test:property
+
 # Run tests with UI
 npm run test:ui
 
@@ -74,12 +78,23 @@ describe('When an AI asks "What transits is Bowen experiencing today?"', () => {
 2. **Orchestration lane:** Fast deterministic tests with injected mocks/fakes
 3. **Filesystem/profile lane:** Temp-fs integration style for precedence and parsing
 4. **Validation lane:** Cross-check production outputs with oracle comparators
+5. **Property lane:** Generated invariant checks with `fast-check`
+
+### Property Lane
+- Property tests live under `tests/property/`.
+- Seeded reruns are supported via:
+  - `ASTRO_PROPERTY_SEED`
+  - `ASTRO_PROPERTY_RUNS`
+  - `ASTRO_PROPERTY_HEAVY_RUNS`
+- This lane is additive and intentionally separate from `quality:gate` for now.
+- Use it for invariants, determinism, and shrinkable counterexamples rather than external parity.
 
 ## Current Status
 
 ✅ **Completed:**
 - Unit suites for service, CLI, registry, domain calculators, and profile store
 - Validation harness with subsystem comparators and dense root oracle
+- Property-test lane for generated invariants across time utils, services, houses, and transits
 - Deterministic time setup and fixture-driven real-world chart checks
 
 ## Known Issues

package/tests/property/electional-service.property.test.ts

@@ -0,0 +1,67 @@
+import fc from 'fast-check';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { GetElectionalContextInput } from '../../src/astro-service/service-types.js';
+import type { InternalValidationAdapter } from '../validation/adapters/internal.js';
+import {
+  dateOnlyArb,
+  electionalHouseSystemArb,
+  longitudeArb,
+  nonPolarLatitudeArb,
+  polarLatitudeArb,
+  timezoneArb,
+} from './helpers/arbitraries.js';
+import { propertyConfig } from './helpers/config.js';
+import { getInternalValidationAdapter } from './helpers/runtime.js';
+
+const SUPPORTED_ELECTIONAL_SYSTEMS = ['P', 'K', 'W', 'R'] as const;
+
+describe('Property: electional service', () => {
+  let adapter: InternalValidationAdapter;
+
+  beforeAll(async () => {
+    adapter = await getInternalValidationAdapter();
+  });
+
+  it('keeps sect classification, warnings, and optional fields aligned with the contract', async () => {
+    const electionalInputArb = fc.record({
+      date: dateOnlyArb,
+      time: fc.constantFrom('00:00', '06:00', '12:00', '18:00', '23:30'),
+      timezone: timezoneArb,
+      latitude: fc.oneof(nonPolarLatitudeArb, polarLatitudeArb),
+      longitude: longitudeArb,
+      house_system: electionalHouseSystemArb,
+      include_ruler_basics: fc.boolean(),
+      include_planetary_applications: fc.boolean(),
+      orb_degrees: fc.double({
+        min: 0.5,
+        max: 5,
+        noNaN: true,
+        noDefaultInfinity: true,
+      }),
+    });
+
+    await fc.assert(
+      fc.property(electionalInputArb, (input) => {
+        const result = adapter.getElectionalContext(input satisfies GetElectionalContextInput);
+
+        expect(result.classification).toBe(result.rawSunAltitudeDegrees >= 0 ? 'day' : 'night');
+        expect(result.isDayChart).toBe(result.rawSunAltitudeDegrees >= 0);
+        expect(SUPPORTED_ELECTIONAL_SYSTEMS).toContain(result.houseSystem);
+
+        const horizonWarning = result.warnings.some((warning) => warning.includes('near the horizon'));
+        expect(horizonWarning).toBe(Math.abs(result.rawSunAltitudeDegrees) < 0.5);
+
+        const fallbackWarning = result.warnings.some((warning) =>
+          warning.includes('House calculation fell back')
+        );
+        expect(fallbackWarning).toBe(result.houseSystem !== input.house_system);
+
+        expect(result.hasApplyingAspects).toBe(input.include_planetary_applications);
+        expect(result.hasMoonApplyingAspects).toBe(input.include_planetary_applications);
+        expect(result.hasRulerBasics).toBe(input.include_ruler_basics);
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+});
+

package/tests/property/helpers/arbitraries.ts

@@ -0,0 +1,126 @@
+import fc from 'fast-check';
+import { utcToLocal } from '../../../src/time-utils.js';
+import type { ElectionalHouseSystem, HouseSystem } from '../../../src/types.js';
+
+export const REPRESENTATIVE_TIMEZONES = [
+  'UTC',
+  'America/Los_Angeles',
+  'America/New_York',
+  'Europe/London',
+  'Europe/Berlin',
+  'Asia/Tokyo',
+  'Asia/Kolkata',
+  'Asia/Kathmandu',
+  'Australia/Sydney',
+  'Pacific/Auckland',
+  'Pacific/Chatham',
+] as const;
+
+export const NON_HOUR_OFFSET_TIMEZONES = [
+  'Asia/Kolkata',
+  'Asia/Kathmandu',
+  'Pacific/Chatham',
+] as const;
+
+export const SUPPORTED_HOUSE_SYSTEMS = [
+  'P',
+  'K',
+  'W',
+  'E',
+  'O',
+  'R',
+  'C',
+  'A',
+  'V',
+  'X',
+  'H',
+  'T',
+  'B',
+] as const satisfies readonly HouseSystem[];
+
+export const ELECTIONAL_HOUSE_SYSTEMS = [
+  'P',
+  'K',
+  'W',
+  'R',
+] as const satisfies readonly ElectionalHouseSystem[];
+
+const MIN_UTC_DATE = new Date('2000-01-01T00:00:00Z');
+const MAX_UTC_DATE = new Date('2035-12-31T23:59:59Z');
+
+export const timezoneArb = fc.constantFrom(...REPRESENTATIVE_TIMEZONES);
+export const nonHourTimezoneArb = fc.constantFrom(...NON_HOUR_OFFSET_TIMEZONES);
+export const utcDateArb = fc
+  .date({ min: MIN_UTC_DATE, max: MAX_UTC_DATE })
+  .filter((date) => Number.isFinite(date.getTime()));
+export const dateOnlyArb = utcDateArb.map(formatDateOnly);
+export const minuteArb = fc.integer({ min: 0, max: 59 });
+export const secondArb = fc.integer({ min: 0, max: 59 });
+export const nonPolarLatitudeArb = fc.double({
+  min: -65,
+  max: 65,
+  noNaN: true,
+  noDefaultInfinity: true,
+});
+export const polarLatitudeArb = fc.oneof(
+  fc.double({ min: 66.1, max: 80, noNaN: true, noDefaultInfinity: true }),
+  fc.double({ min: -80, max: -66.1, noNaN: true, noDefaultInfinity: true })
+);
+export const longitudeArb = fc.double({
+  min: -180,
+  max: 180,
+  noNaN: true,
+  noDefaultInfinity: true,
+});
+export const houseSystemArb = fc.constantFrom(...SUPPORTED_HOUSE_SYSTEMS);
+export const electionalHouseSystemArb = fc.constantFrom(...ELECTIONAL_HOUSE_SYSTEMS);
+
+export const validLocalDateTimeArb = timezoneArb.chain((timezone) =>
+  fc
+    .record({
+      date: utcDateArb,
+      minute: minuteArb,
+      second: secondArb,
+    })
+    .map(({ date, minute, second }) => {
+      const localDate = utcToLocal(date, timezone);
+      return {
+        timezone,
+        local: {
+          year: localDate.year,
+          month: localDate.month,
+          day: localDate.day,
+          hour: 12,
+          minute,
+          second,
+        },
+      };
+    })
+);
+
+export const nonHourLocalDateTimeArb = nonHourTimezoneArb.chain((timezone) =>
+  fc
+    .record({
+      date: utcDateArb,
+      minute: minuteArb,
+      second: secondArb,
+    })
+    .map(({ date, minute, second }) => {
+      const localDate = utcToLocal(date, timezone);
+      return {
+        timezone,
+        local: {
+          year: localDate.year,
+          month: localDate.month,
+          day: localDate.day,
+          hour: 12,
+          minute,
+          second,
+        },
+      };
+    })
+);
+
+export function formatDateOnly(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}

package/tests/property/helpers/config.ts

@@ -0,0 +1,52 @@
+const DEFAULT_PROPERTY_RUNS = 100;
+const DEFAULT_HEAVY_PROPERTY_RUNS = 25;
+
+function readPositiveIntegerEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer when provided.`);
+  }
+
+  return parsed;
+}
+
+function readOptionalIntegerEnv(name: string): number | undefined {
+  const raw = process.env[name];
+  if (!raw) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative integer when provided.`);
+  }
+
+  return parsed;
+}
+
+const sharedSeed = readOptionalIntegerEnv('ASTRO_PROPERTY_SEED');
+const defaultRuns = readPositiveIntegerEnv('ASTRO_PROPERTY_RUNS', DEFAULT_PROPERTY_RUNS);
+const defaultHeavyRuns = readPositiveIntegerEnv(
+  'ASTRO_PROPERTY_HEAVY_RUNS',
+  DEFAULT_HEAVY_PROPERTY_RUNS
+);
+
+/**
+ * Standard `fast-check` execution parameters for this repo's property lane.
+ *
+ * @remarks
+ * All failures should remain reproducible by rerunning with the reported seed,
+ * or by overriding `ASTRO_PROPERTY_SEED` and the run-count env vars locally.
+ */
+export function propertyConfig(options: { heavy?: boolean } = {}) {
+  return {
+    numRuns: options.heavy ? defaultHeavyRuns : defaultRuns,
+    ...(sharedSeed !== undefined ? { seed: sharedSeed } : {}),
+    verbose: 1 as const,
+  };
+}

package/tests/property/helpers/runtime.ts

@@ -0,0 +1,12 @@
+import { InternalValidationAdapter } from '../../validation/adapters/internal.js';
+
+let sharedAdapterPromise: Promise<InternalValidationAdapter> | undefined;
+
+/**
+ * Reuse a single initialized adapter per property-test worker so ephemeris
+ * startup cost does not scale with generated cases.
+ */
+export function getInternalValidationAdapter(): Promise<InternalValidationAdapter> {
+  sharedAdapterPromise ??= InternalValidationAdapter.create();
+  return sharedAdapterPromise;
+}

package/tests/property/houses.property.test.ts

@@ -0,0 +1,74 @@
+import fc from 'fast-check';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { InternalValidationAdapter } from '../validation/adapters/internal.js';
+import {
+  dateOnlyArb,
+  houseSystemArb,
+  longitudeArb,
+  nonPolarLatitudeArb,
+  polarLatitudeArb,
+} from './helpers/arbitraries.js';
+import { propertyConfig } from './helpers/config.js';
+import { getInternalValidationAdapter } from './helpers/runtime.js';
+
+function toIsoAtNoon(date: string): string {
+  return `${date}T12:00:00Z`;
+}
+
+function angleDeltaDegrees(left: number, right: number): number {
+  return (right - left + 360) % 360;
+}
+
+describe('Property: houses', () => {
+  let adapter: InternalValidationAdapter;
+
+  beforeAll(async () => {
+    adapter = await getInternalValidationAdapter();
+  });
+
+  it('keeps house outputs inside valid longitude ranges', async () => {
+    await fc.assert(
+      fc.property(dateOnlyArb, nonPolarLatitudeArb, longitudeArb, houseSystemArb, (date, latitude, longitude, houseSystem) => {
+        const result = adapter.getHouseResult(toIsoAtNoon(date), latitude, longitude, houseSystem);
+
+        expect(result.cusps).toHaveLength(12);
+        for (const value of [...result.cusps, result.ascendant, result.mc]) {
+          expect(value).toBeGreaterThanOrEqual(0);
+          expect(value).toBeLessThan(360);
+        }
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+
+  it('keeps Whole Sign and Equal cusps spaced by 30 degrees', async () => {
+    await fc.assert(
+      fc.property(dateOnlyArb, nonPolarLatitudeArb, longitudeArb, fc.constantFrom('W' as const, 'E' as const), (date, latitude, longitude, houseSystem) => {
+        const result = adapter.getHouseResult(toIsoAtNoon(date), latitude, longitude, houseSystem);
+
+        for (let index = 0; index < result.cusps.length; index += 1) {
+          const current = result.cusps[index];
+          const next = result.cusps[(index + 1) % result.cusps.length];
+          expect(Math.abs(angleDeltaDegrees(current, next) - 30)).toBeLessThan(0.05);
+        }
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+
+  it('only falls back to Whole Sign in polar edge cases', async () => {
+    await fc.assert(
+      fc.property(dateOnlyArb, polarLatitudeArb, longitudeArb, houseSystemArb, (date, latitude, longitude, houseSystem) => {
+        const result = adapter.getHouseResult(toIsoAtNoon(date), latitude, longitude, houseSystem);
+
+        if (houseSystem === 'W') {
+          expect(result.system).toBe('W');
+        } else if (result.system !== houseSystem) {
+          expect(result.system).toBe('W');
+        }
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+});
+

package/tests/property/rising-sign-service.property.test.ts

@@ -0,0 +1,255 @@
+import fc from 'fast-check';
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+  addLocalDays,
+  formatLocalTimestampWithOffset,
+  localToUTC,
+} from '../../src/time-utils.js';
+import type { GetRisingSignWindowsInput } from '../../src/astro-service/service-types.js';
+import type { InternalValidationAdapter } from '../validation/adapters/internal.js';
+import type { NormalizedRisingSignWindowResult } from '../validation/utils/fixtureTypes.js';
+import {
+  dateOnlyArb,
+  longitudeArb,
+  nonPolarLatitudeArb,
+  timezoneArb,
+} from './helpers/arbitraries.js';
+import { propertyConfig } from './helpers/config.js';
+import { getInternalValidationAdapter } from './helpers/runtime.js';
+
+const DST_FIXTURES: Array<Omit<GetRisingSignWindowsInput, 'mode'>> = [
+  {
+    date: '2024-03-10',
+    latitude: 34.0522,
+    longitude: -118.2437,
+    timezone: 'America/Los_Angeles',
+  },
+  {
+    date: '2024-11-03',
+    latitude: 34.0522,
+    longitude: -118.2437,
+    timezone: 'America/Los_Angeles',
+  },
+  {
+    date: '2024-03-31',
+    latitude: 51.5074,
+    longitude: -0.1278,
+    timezone: 'Europe/London',
+  },
+] as const;
+
+function assertFullDayCoverage(
+  result: NormalizedRisingSignWindowResult,
+  input: Pick<GetRisingSignWindowsInput, 'date' | 'timezone'>
+): void {
+  expect(result.windows.length).toBeGreaterThan(0);
+
+  const [firstWindow] = result.windows;
+  const lastWindow = result.windows[result.windows.length - 1];
+  const expectedStart = formatLocalTimestampWithOffset(
+    localToUTC(
+      {
+        year: Number.parseInt(input.date.slice(0, 4), 10),
+        month: Number.parseInt(input.date.slice(5, 7), 10),
+        day: Number.parseInt(input.date.slice(8, 10), 10),
+        hour: 0,
+        minute: 0,
+        second: 0,
+      },
+      input.timezone
+    ),
+    input.timezone
+  );
+  const expectedEnd = formatLocalTimestampWithOffset(
+    addLocalDays(
+      {
+        year: Number.parseInt(input.date.slice(0, 4), 10),
+        month: Number.parseInt(input.date.slice(5, 7), 10),
+        day: Number.parseInt(input.date.slice(8, 10), 10),
+        hour: 0,
+        minute: 0,
+        second: 0,
+      },
+      input.timezone,
+      1
+    ),
+    input.timezone
+  );
+
+  expect(firstWindow.start).toBe(expectedStart);
+  expect(lastWindow.end).toBe(expectedEnd);
+
+  for (const [index, window] of result.windows.entries()) {
+    const startMs = new Date(window.start).getTime();
+    const endMs = new Date(window.end).getTime();
+
+    expect(window.start).toMatch(/[+-]\d{2}:\d{2}$/);
+    expect(window.end).toMatch(/[+-]\d{2}:\d{2}$/);
+    expect(endMs).toBeGreaterThan(startMs);
+    expect(window.durationMs).toBe(endMs - startMs);
+
+    if (index > 0) {
+      expect(window.start).toBe(result.windows[index - 1].end);
+    }
+  }
+}
+
+function estimateBoundaryErrorMs(
+  adapter: InternalValidationAdapter,
+  boundaryUtc: Date,
+  latitude: number,
+  longitude: number,
+  fromSign: string
+): number {
+  const searchRadiusMs = 2 * 60 * 60 * 1000;
+  const stepMs = 60 * 1000;
+  let previousTime = new Date(boundaryUtc.getTime() - searchRadiusMs);
+  let previousSign = adapter.getAscendantSignAt(previousTime.toISOString(), latitude, longitude);
+
+  for (
+    let currentMs = previousTime.getTime() + stepMs;
+    currentMs <= boundaryUtc.getTime() + searchRadiusMs;
+    currentMs += stepMs
+  ) {
+    const currentTime = new Date(currentMs);
+    const currentSign = adapter.getAscendantSignAt(currentTime.toISOString(), latitude, longitude);
+
+    if (previousSign === fromSign && currentSign !== fromSign) {
+      return Math.abs(boundaryUtc.getTime() - currentMs);
+    }
+
+    previousTime = currentTime;
+    previousSign = currentSign;
+  }
+
+  throw new Error(`Unable to bracket rising-sign transition near ${boundaryUtc.toISOString()}.`);
+}
+
+function collapseConsecutiveWindows(result: NormalizedRisingSignWindowResult) {
+  const collapsed: NormalizedRisingSignWindowResult['windows'] = [];
+
+  for (const window of result.windows) {
+    const previous = collapsed[collapsed.length - 1];
+    if (!previous || previous.sign !== window.sign) {
+      collapsed.push({ ...window });
+      continue;
+    }
+
+    previous.end = window.end;
+    previous.durationMs += window.durationMs;
+  }
+
+  return collapsed;
+}
+
+function findSubsequenceIndices(sequence: string[], candidateSubsequence: string[]): number[] | null {
+  const indices: number[] = [];
+  let cursor = 0;
+
+  for (const sign of candidateSubsequence) {
+    while (cursor < sequence.length && sequence[cursor] !== sign) {
+      cursor += 1;
+    }
+
+    if (cursor >= sequence.length) {
+      return null;
+    }
+
+    indices.push(cursor);
+    cursor += 1;
+  }
+
+  return indices;
+}
+
+describe('Property: rising-sign service', () => {
+  let adapter: InternalValidationAdapter;
+
+  beforeAll(async () => {
+    adapter = await getInternalValidationAdapter();
+  });
+
+  it('covers a full local day with contiguous exact-mode windows', async () => {
+    const exactInputArb = fc.record({
+      date: dateOnlyArb,
+      latitude: nonPolarLatitudeArb,
+      longitude: longitudeArb,
+      timezone: timezoneArb,
+    });
+
+    await fc.assert(
+      fc.property(exactInputArb, (baseInput) => {
+        const input: GetRisingSignWindowsInput = { ...baseInput, mode: 'exact' };
+        const first = adapter.getRisingSignWindows(input);
+        const second = adapter.getRisingSignWindows(input);
+
+        expect(second).toEqual(first);
+        assertFullDayCoverage(first, input);
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+
+  it('keeps exact-mode boundaries at least as precise as approximate mode', async () => {
+    const comparisonInputArb = fc.record({
+      date: dateOnlyArb,
+      latitude: nonPolarLatitudeArb,
+      longitude: longitudeArb,
+      timezone: timezoneArb,
+    });
+
+    await fc.assert(
+      fc.property(comparisonInputArb, (baseInput) => {
+        const approximate = adapter.getRisingSignWindows({ ...baseInput, mode: 'approximate' });
+        const exact = adapter.getRisingSignWindows({ ...baseInput, mode: 'exact' });
+        const collapsedApproximate = collapseConsecutiveWindows(approximate);
+        const collapsedExact = collapseConsecutiveWindows(exact);
+        const exactSigns = collapsedExact.map((window) => window.sign);
+        const approximateSigns = collapsedApproximate.map((window) => window.sign);
+        const matchingIndices = findSubsequenceIndices(exactSigns, approximateSigns);
+
+        expect(matchingIndices).not.toBeNull();
+
+        for (let index = 0; index < collapsedApproximate.length - 1; index += 1) {
+          const exactFromIndex = matchingIndices![index];
+          const fromSign = collapsedApproximate[index].sign;
+          const exactBoundary = new Date(collapsedExact[exactFromIndex].end);
+          const approximateBoundary = new Date(collapsedApproximate[index].end);
+
+          const exactError = estimateBoundaryErrorMs(
+            adapter,
+            exactBoundary,
+            baseInput.latitude,
+            baseInput.longitude,
+            fromSign
+          );
+          const approximateError = estimateBoundaryErrorMs(
+            adapter,
+            approximateBoundary,
+            baseInput.latitude,
+            baseInput.longitude,
+            fromSign
+          );
+
+          expect(exactError).toBeLessThanOrEqual(approximateError + 60_000);
+        }
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+
+  it('keeps DST-transition days contiguous and fully covered', async () => {
+    await fc.assert(
+      fc.property(fc.constantFrom(...DST_FIXTURES), (baseInput) => {
+        const result = adapter.getRisingSignWindows({ ...baseInput, mode: 'exact' });
+        assertFullDayCoverage(result, baseInput);
+
+        const offsets = new Set(
+          result.windows.flatMap((window) => [window.start.slice(-6), window.end.slice(-6)])
+        );
+        expect(offsets.size).toBeGreaterThanOrEqual(2);
+      }),
+      propertyConfig({ heavy: true })
+    );
+  });
+});