ether-to-astro 1.0.0

package/tests/validation/fixtures/positions/core.ts

@@ -0,0 +1,159 @@
+import { PLANETS } from '../../../../src/types.js';
+import type { PositionFixture } from '../../utils/fixtureTypes.js';
+
+export const positionFixtures: PositionFixture[] = [
+  {
+    name: 'spring-equinox-window',
+    isoUtc: '2024-03-26T12:00:00Z',
+    planetIds: [PLANETS.SUN, PLANETS.MOON, PLANETS.MERCURY, PLANETS.PLUTO],
+    expected: [
+      {
+        body: 'Sun',
+        longitude: 6.316731386907804,
+        latitude: -0.00007352800431972934,
+        speed: 0.9897125520461556,
+        retrograde: false,
+      },
+      {
+        body: 'Moon',
+        longitude: 199.48694064839447,
+        latitude: -0.36176675515418294,
+        speed: 11.941713114615638,
+        retrograde: false,
+      },
+      {
+        body: 'Mercury',
+        longitude: 24.69285200607294,
+        latitude: 2.672580045178339,
+        speed: 0.7867951188862425,
+        retrograde: false,
+      },
+      {
+        body: 'Pluto',
+        longitude: 301.7781198496598,
+        latitude: -2.927662494192267,
+        speed: 0.017128737345548647,
+        retrograde: false,
+      },
+    ],
+  },
+  {
+    name: 'mercury-retrograde',
+    isoUtc: '2024-04-10T12:00:00Z',
+    planetIds: [PLANETS.MERCURY, PLANETS.VENUS, PLANETS.MARS],
+    expected: [
+      {
+        body: 'Mercury',
+        longitude: 23.614957304937263,
+        latitude: 2.529284646399885,
+        speed: -0.7176024601820039,
+        retrograde: true,
+      },
+      {
+        body: 'Venus',
+        longitude: 6.588795330387654,
+        latitude: -1.4940621615222225,
+        speed: 1.2350609766572045,
+        retrograde: false,
+      },
+      {
+        body: 'Mars',
+        longitude: 344.4004646784754,
+        latitude: -1.2486830823566866,
+        speed: 0.7771414567155127,
+        retrograde: false,
+      },
+    ],
+  },
+  {
+    name: 'slow-movers',
+    isoUtc: '2025-01-15T00:00:00Z',
+    planetIds: [PLANETS.SATURN, PLANETS.URANUS, PLANETS.NEPTUNE, PLANETS.PLUTO],
+    expected: [
+      {
+        body: 'Saturn',
+        longitude: 345.7060989429216,
+        latitude: -1.9494898994552385,
+        speed: 0.0926345534031346,
+        retrograde: false,
+      },
+      {
+        body: 'Uranus',
+        longitude: 53.36875615623478,
+        latitude: -0.24802075433686954,
+        speed: -0.013507214995734195,
+        retrograde: true,
+      },
+      {
+        body: 'Neptune',
+        longitude: 357.54312216762855,
+        latitude: -1.2774823347799653,
+        speed: 0.02110562924597566,
+        retrograde: false,
+      },
+      {
+        body: 'Pluto',
+        longitude: 301.5060850985308,
+        latitude: -3.288200764433513,
+        speed: 0.032129088743535324,
+        retrograde: false,
+      },
+    ],
+  },
+  {
+    name: 'millennium',
+    isoUtc: '2000-01-01T12:00:00Z',
+    planetIds: [PLANETS.SUN, PLANETS.JUPITER, PLANETS.PLUTO],
+    expected: [
+      {
+        body: 'Sun',
+        longitude: 280.36891967534336,
+        latitude: 0.000232326514176311,
+        speed: 1.0194320944210782,
+        retrograde: false,
+      },
+      {
+        body: 'Jupiter',
+        longitude: 25.253030309421774,
+        latitude: -1.2621728355212258,
+        speed: 0.040761317651403686,
+        retrograde: false,
+      },
+      {
+        body: 'Pluto',
+        longitude: 251.4547088467409,
+        latitude: 10.855202461622458,
+        speed: 0.035152902046821095,
+        retrograde: false,
+      },
+    ],
+  },
+  {
+    name: 'far-future',
+    isoUtc: '2099-12-31T00:00:00Z',
+    planetIds: [PLANETS.SUN, PLANETS.MERCURY, PLANETS.NEPTUNE],
+    expected: [
+      {
+        body: 'Sun',
+        longitude: 279.58558664635507,
+        latitude: 0.00011630013927636058,
+        speed: 1.0187919739012508,
+        retrograde: false,
+      },
+      {
+        body: 'Mercury',
+        longitude: 286.38509679515437,
+        latitude: -2.0863288163781823,
+        speed: 1.6192452202966239,
+        retrograde: false,
+      },
+      {
+        body: 'Neptune',
+        longitude: 167.29740813269177,
+        latitude: 0.963176276464019,
+        speed: -0.006626443683328727,
+        retrograde: true,
+      },
+    ],
+  },
+];

package/tests/validation/fixtures/rise-set/core.ts

@@ -0,0 +1,20 @@
+import { PLANETS } from '../../../../src/types.js';
+import type { RiseSetFixture } from '../../utils/fixtureTypes.js';
+
+export const riseSetFixtures: RiseSetFixture[] = [
+  {
+    name: 'los-angeles-next-events',
+    isoUtc: '2024-03-26T20:30:00Z',
+    latitude: 34.0522,
+    longitude: -118.2437,
+    planetId: PLANETS.SUN,
+  },
+  {
+    name: 'high-latitude-no-rise-no-set',
+    isoUtc: '2024-12-21T00:00:00Z',
+    latitude: 78.2232,
+    longitude: 15.6267,
+    planetId: PLANETS.SUN,
+    expectedNoRiseSet: true,
+  },
+];

package/tests/validation/fixtures/roots/core.ts

@@ -0,0 +1,47 @@
+import { PLANETS } from '../../../../src/types.js';
+import type { RootFixture } from '../../utils/fixtureTypes.js';
+
+export const rootFixtures: RootFixture[] = [
+  {
+    name: 'sign-change-root',
+    planetId: PLANETS.MOON,
+    targetLongitude: 180,
+    startIsoUtc: '2024-01-01T00:00:00Z',
+    endIsoUtc: '2024-01-20T00:00:00Z',
+    expectedMinRoots: 1,
+    expectedMaxRoots: 1,
+  },
+  {
+    name: 'endpoint-near-root',
+    planetId: PLANETS.SUN,
+    targetFromStartLongitude: true,
+    startIsoUtc: '2024-03-20T00:00:00Z',
+    endIsoUtc: '2024-03-30T00:00:00Z',
+    expectedMinRoots: 1,
+  },
+  {
+    name: 'no-root-interval',
+    planetId: PLANETS.SUN,
+    targetLongitude: 0,
+    startIsoUtc: '2024-03-01T00:00:00Z',
+    endIsoUtc: '2024-03-05T00:00:00Z',
+    expectedMinRoots: 0,
+    expectedMaxRoots: 0,
+  },
+  {
+    name: 'multiple-root-interval',
+    planetId: PLANETS.MOON,
+    targetLongitude: 0,
+    startIsoUtc: '2024-01-01T00:00:00Z',
+    endIsoUtc: '2024-03-01T00:00:00Z',
+    expectedMinRoots: 2,
+  },
+  {
+    name: 'tangential-mercury-station',
+    planetId: PLANETS.MERCURY,
+    targetFromSampledMinimum: { samples: 96 },
+    startIsoUtc: '2023-12-11T00:00:00Z',
+    endIsoUtc: '2023-12-15T00:00:00Z',
+    expectedMinRoots: 1,
+  },
+];

package/tests/validation/fixtures/transits/core.ts

@@ -0,0 +1,61 @@
+import { PLANETS } from '../../../../src/types.js';
+import type { TransitFixture } from '../../utils/fixtureTypes.js';
+
+export const transitFixtures: TransitFixture[] = [
+  {
+    name: 'applying-square-policy',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.MARS,
+    natalPlanetId: PLANETS.VENUS,
+    natalOffsetDegrees: 92,
+    expectedAspect: 'square',
+    expectedIsApplying: true,
+    expectExactTimeStatus: 'within_preview',
+  },
+  {
+    name: 'separating-square-policy',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.MARS,
+    natalPlanetId: PLANETS.VENUS,
+    natalOffsetDegrees: 88,
+    expectedAspect: 'square',
+    expectedIsApplying: false,
+    expectExactTimeStatus: 'within_preview',
+  },
+  {
+    name: 'orb-too-wide-status-undefined',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.MARS,
+    natalPlanetId: PLANETS.VENUS,
+    natalOffsetDegrees: 3,
+    expectedAspect: 'conjunction',
+    expectExactTimeStatus: 'undefined',
+  },
+  {
+    name: 'dual-target-trine',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.JUPITER,
+    natalPlanetId: PLANETS.SUN,
+    natalOffsetDegrees: 120,
+    expectedAspect: 'trine',
+    expectExactTimeStatus: 'within_preview',
+  },
+  {
+    name: 'dual-target-sextile',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.MARS,
+    natalPlanetId: PLANETS.SUN,
+    natalOffsetDegrees: 60,
+    expectedAspect: 'sextile',
+    expectExactTimeStatus: 'within_preview',
+  },
+  {
+    name: 'opposition-case',
+    currentIsoUtc: '2024-03-15T00:00:00Z',
+    transitingPlanetId: PLANETS.JUPITER,
+    natalPlanetId: PLANETS.MARS,
+    natalOffsetDegrees: 180,
+    expectedAspect: 'opposition',
+    expectExactTimeStatus: 'within_preview',
+  },
+];

package/tests/validation/fixtures/transits/dst.ts

@@ -0,0 +1,21 @@
+export interface DstFixture {
+  name: string;
+  timezone: string;
+  local: { year: number; month: number; day: number; hour: number; minute: number };
+  kind: 'ambiguous' | 'nonexistent';
+}
+
+export const dstFixtures: DstFixture[] = [
+  {
+    name: 'dst-ambiguous-local-time',
+    timezone: 'America/New_York',
+    local: { year: 2024, month: 11, day: 3, hour: 1, minute: 30 },
+    kind: 'ambiguous',
+  },
+  {
+    name: 'dst-nonexistent-local-time',
+    timezone: 'America/New_York',
+    local: { year: 2024, month: 3, day: 10, hour: 2, minute: 30 },
+    kind: 'nonexistent',
+  },
+];

package/tests/validation/oracle.spec.ts

@@ -0,0 +1,129 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { EphemerisCalculator } from '../../src/ephemeris.js';
+import { PLANETS } from '../../src/types.js';
+import { denseScanRootOracleWithDebug } from './utils/denseRootOracle.js';
+
+function shortestDiff(longitude: number, targetLongitude: number): number {
+  let diff = (((longitude % 360) + 360) % 360) - (((targetLongitude % 360) + 360) % 360);
+  if (diff > 180) diff -= 360;
+  if (diff < -180) diff += 360;
+  return diff;
+}
+
+describe('Dense Root Oracle', () => {
+  let ephem: EphemerisCalculator;
+
+  beforeAll(async () => {
+    ephem = new EphemerisCalculator();
+    await ephem.init();
+  });
+
+  it('finds multiple Moon crossings in a multi-week interval', () => {
+    const start = ephem.dateToJulianDay(new Date('2024-01-01T00:00:00Z'));
+    const end = ephem.dateToJulianDay(new Date('2024-03-01T00:00:00Z'));
+    const target = 0;
+    const result = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.MOON, jd).longitude,
+      target,
+      start,
+      end
+    );
+
+    expect(result.roots.length).toBeGreaterThanOrEqual(2);
+    for (const jd of result.roots) {
+      const lon = ephem.getPlanetPosition(PLANETS.MOON, jd).longitude;
+      expect(Math.abs(shortestDiff(lon, target))).toBeLessThan(0.05);
+    }
+  });
+
+  it('is symmetric around wrap targets (0° vs 359.9°)', () => {
+    const start = ephem.dateToJulianDay(new Date('2024-03-19T00:00:00Z'));
+    const end = ephem.dateToJulianDay(new Date('2024-03-22T00:00:00Z'));
+
+    const at0 = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.SUN, jd).longitude,
+      0,
+      start,
+      end
+    ).roots;
+    const at3599 = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.SUN, jd).longitude,
+      359.9,
+      start,
+      end
+    ).roots;
+
+    expect(at0.length).toBeGreaterThan(0);
+    expect(at3599.length).toBeGreaterThan(0);
+    expect(Math.abs(at0[0] - at3599[0])).toBeLessThan(1);
+  });
+
+  it('captures tangential near-station root behavior', () => {
+    const start = ephem.dateToJulianDay(new Date('2023-12-11T00:00:00Z'));
+    const end = ephem.dateToJulianDay(new Date('2023-12-15T00:00:00Z'));
+
+    let minLon = Number.POSITIVE_INFINITY;
+    for (let i = 0; i <= 96; i++) {
+      const jd = start + (i * (end - start)) / 96;
+      const lon = ephem.getPlanetPosition(PLANETS.MERCURY, jd).longitude;
+      if (lon < minLon) minLon = lon;
+    }
+
+    const result = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.MERCURY, jd).longitude,
+      minLon,
+      start,
+      end
+    );
+
+    expect(result.roots.length).toBeGreaterThan(0);
+    const jd = result.roots[0];
+    const lon = ephem.getPlanetPosition(PLANETS.MERCURY, jd).longitude;
+    expect(Math.abs(shortestDiff(lon, minLon))).toBeLessThan(0.05);
+  });
+
+  it('keeps endpoint-near-root cases', () => {
+    const start = ephem.dateToJulianDay(new Date('2024-03-20T00:00:00Z'));
+    const end = ephem.dateToJulianDay(new Date('2024-03-30T00:00:00Z'));
+    const target = ephem.getPlanetPosition(PLANETS.SUN, start).longitude;
+    const result = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.SUN, jd).longitude,
+      target,
+      start,
+      end
+    );
+
+    expect(result.roots.length).toBeGreaterThan(0);
+    expect(Math.abs(result.roots[0] - start)).toBeLessThan(1 / 24); // within ~1 hour
+  });
+
+  it('oracle roots are self-consistent (crossing or tangential minimum)', () => {
+    const start = ephem.dateToJulianDay(new Date('2024-01-01T00:00:00Z'));
+    const end = ephem.dateToJulianDay(new Date('2024-01-20T00:00:00Z'));
+    const target = 0;
+    const result = denseScanRootOracleWithDebug(
+      (jd) => ephem.getPlanetPosition(PLANETS.MOON, jd).longitude,
+      target,
+      start,
+      end
+    );
+
+    const epsilon = 5 / 1440; // 5 minutes
+    for (const root of result.roots) {
+      const before = ephem.getPlanetPosition(PLANETS.MOON, root - epsilon).longitude;
+      const at = ephem.getPlanetPosition(PLANETS.MOON, root).longitude;
+      const after = ephem.getPlanetPosition(PLANETS.MOON, root + epsilon).longitude;
+      const dBefore = shortestDiff(before, target);
+      const dAt = shortestDiff(at, target);
+      const dAfter = shortestDiff(after, target);
+      const crossing = dBefore === 0 || dAfter === 0 || Math.sign(dBefore) !== Math.sign(dAfter);
+      const tangentialMin =
+        Math.abs(dAt) <= Math.abs(dBefore) &&
+        Math.abs(dAt) <= Math.abs(dAfter) &&
+        Math.abs(dAt) < 0.1;
+
+      expect(crossing || tangentialMin).toBe(true);
+      expect(Math.abs(dAt)).toBeLessThan(0.1);
+    }
+  });
+});

package/tests/validation/utils/denseRootOracle.ts

@@ -0,0 +1,269 @@
+import { minutesToDays, TOLERANCES } from './tolerances.js';
+
+interface Sample {
+  jd: number;
+  longitude: number;
+  shortestDiff: number;
+  phi: number; // Unwrapped raw phase (longitude - target), continuous over interval.
+}
+
+export interface OracleDebugInfo {
+  toleranceDeg: number;
+  sampleStepDays: number;
+  dedupeEpsilonDays: number;
+  samples: Array<{
+    jd: number;
+    isoUtc?: string;
+    longitude: number;
+    shortestDiff: number;
+    phi: number;
+  }>;
+  crossings: Array<{
+    k: number;
+    startJD: number;
+    endJD: number;
+  }>;
+  sanityWarnings: string[];
+}
+
+interface OracleOptions {
+  toleranceDeg?: number;
+  maxStepDays?: number;
+  dedupeEpsilonDays?: number;
+  maxIterations?: number;
+  toIsoUtc?: (jd: number) => string;
+}
+
+function normalizeAngle(angle: number): number {
+  return ((angle % 360) + 360) % 360;
+}
+
+function signedShortestDiff(longitude: number, targetLongitude: number): number {
+  let diff = normalizeAngle(longitude) - normalizeAngle(targetLongitude);
+  if (diff > 180) diff -= 360;
+  if (diff < -180) diff += 360;
+  return diff;
+}
+
+function dedupeSortedRoots(roots: number[], epsilonDays: number): number[] {
+  const deduped: number[] = [];
+  for (const root of roots) {
+    const last = deduped[deduped.length - 1];
+    if (last == null || Math.abs(root - last) > epsilonDays) {
+      deduped.push(root);
+    }
+  }
+  return deduped;
+}
+
+function unwrapNextPhi(prevPhi: number, rawPhase: number): number {
+  let candidate = rawPhase;
+  while (candidate - prevPhi > 180) candidate -= 360;
+  while (candidate - prevPhi < -180) candidate += 360;
+  return candidate;
+}
+
+function enumerateCrossingKs(a: number, b: number): number[] {
+  const lo = Math.min(a, b);
+  const hi = Math.max(a, b);
+  const startK = Math.ceil(lo / 360);
+  const endK = Math.floor(hi / 360);
+  if (startK > endK) return [];
+
+  const ks: number[] = [];
+  for (let k = startK; k <= endK; k++) {
+    ks.push(k);
+  }
+  return ks;
+}
+
+export function denseScanRootOracle(
+  getLongitudeAtJd: (jd: number) => number,
+  targetLongitude: number,
+  startJD: number,
+  endJD: number,
+  options: OracleOptions = {}
+): number[] {
+  return denseScanRootOracleWithDebug(getLongitudeAtJd, targetLongitude, startJD, endJD, options)
+    .roots;
+}
+
+export function denseScanRootOracleWithDebug(
+  getLongitudeAtJd: (jd: number) => number,
+  targetLongitude: number,
+  startJD: number,
+  endJD: number,
+  options: OracleOptions = {}
+): { roots: number[]; debug: OracleDebugInfo } {
+  const toleranceDeg = options.toleranceDeg ?? 0.01;
+  const maxStepDays = options.maxStepDays ?? 0.125; // 3h
+  const dedupeEpsilonDays = options.dedupeEpsilonDays ?? minutesToDays(TOLERANCES.dedupeMinutes);
+  const maxIterations = options.maxIterations ?? 80;
+
+  if (!(startJD < endJD)) {
+    throw new Error(`denseScanRootOracle expected startJD < endJD, got ${startJD} >= ${endJD}`);
+  }
+
+  const spanDays = endJD - startJD;
+  const sampleCount = Math.max(16, Math.ceil(spanDays / maxStepDays));
+  const stepDays = spanDays / sampleCount;
+
+  const samples: Sample[] = [];
+  const sanityWarnings: string[] = [];
+  let prevPhi: number | null = null;
+  for (let i = 0; i <= sampleCount; i++) {
+    const jd = startJD + i * stepDays;
+    const longitude = getLongitudeAtJd(jd);
+    const rawPhase = longitude - targetLongitude;
+    const phi = prevPhi == null ? rawPhase : unwrapNextPhi(prevPhi, rawPhase);
+    const shortestDiff = signedShortestDiff(longitude, targetLongitude);
+
+    // Coarse sanity guard against sampling pathologies in test harness.
+    if (prevPhi != null && Math.abs(phi - prevPhi) > 40) {
+      sanityWarnings.push(
+        `Large phase jump at sample ${i} (Δphi=${(phi - prevPhi).toFixed(3)}° over ${stepDays.toFixed(6)}d)`
+      );
+    }
+
+    samples.push({ jd, longitude, shortestDiff, phi });
+    prevPhi = phi;
+  }
+
+  const roots: number[] = [];
+  const crossings: OracleDebugInfo['crossings'] = [];
+
+  // Endpoint near-zero roots only (avoid over-counting sampled interior points).
+  const startSample = samples[0];
+  const endSample = samples[samples.length - 1];
+  if (Math.abs(startSample.shortestDiff) <= toleranceDeg * 2) {
+    roots.push(startSample.jd);
+  }
+  if (Math.abs(endSample.shortestDiff) <= toleranceDeg * 2) {
+    roots.push(endSample.jd);
+  }
+
+  // Enumerate all k*360 crossings in each sampled interval.
+  for (let i = 0; i < samples.length - 1; i++) {
+    const left = samples[i];
+    const right = samples[i + 1];
+    const ks = enumerateCrossingKs(left.phi, right.phi);
+    if (ks.length === 0) continue;
+
+    for (const k of ks) {
+      const targetPhase = k * 360;
+      crossings.push({ k, startJD: left.jd, endJD: right.jd });
+
+      // If bracket endpoint is already exact, keep a single endpoint root.
+      if (Math.abs(left.shortestDiff) <= toleranceDeg) {
+        roots.push(left.jd);
+        continue;
+      }
+      if (Math.abs(right.shortestDiff) <= toleranceDeg) {
+        roots.push(right.jd);
+        continue;
+      }
+
+      let bLeft = left;
+      let bRight = right;
+      let iterations = 0;
+      let found = false;
+      while (iterations < maxIterations && bRight.jd - bLeft.jd > dedupeEpsilonDays / 4) {
+        const midJD = (bLeft.jd + bRight.jd) / 2;
+        const midLongitude = getLongitudeAtJd(midJD);
+        const midRawPhase = midLongitude - targetLongitude;
+        const midPhi = unwrapNextPhi(bLeft.phi, midRawPhase);
+        const midShortestDiff = signedShortestDiff(midLongitude, targetLongitude);
+
+        if (Math.abs(midShortestDiff) <= toleranceDeg) {
+          roots.push(midJD);
+          found = true;
+          break;
+        }
+
+        if ((bLeft.phi - targetPhase) * (midPhi - targetPhase) <= 0) {
+          bRight = {
+            jd: midJD,
+            longitude: midLongitude,
+            shortestDiff: midShortestDiff,
+            phi: midPhi,
+          };
+        } else {
+          bLeft = {
+            jd: midJD,
+            longitude: midLongitude,
+            shortestDiff: midShortestDiff,
+            phi: midPhi,
+          };
+        }
+        iterations++;
+      }
+
+      if (!found) {
+        roots.push((bLeft.jd + bRight.jd) / 2);
+      }
+    }
+  }
+
+  // Tangential fallback (no crossing required).
+  for (let i = 1; i < samples.length - 1; i++) {
+    const prev = samples[i - 1];
+    const curr = samples[i];
+    const next = samples[i + 1];
+    const prevAbs = Math.abs(prev.shortestDiff);
+    const currAbs = Math.abs(curr.shortestDiff);
+    const nextAbs = Math.abs(next.shortestDiff);
+
+    const isLocalMin =
+      currAbs <= prevAbs && currAbs <= nextAbs && (currAbs < prevAbs || currAbs < nextAbs);
+    if (!isLocalMin) continue;
+
+    const hasPhaseCrossingHere = enumerateCrossingKs(prev.phi, next.phi).length > 0;
+    if (hasPhaseCrossingHere) continue;
+
+    if (currAbs > toleranceDeg * 20) continue;
+
+    let leftJD = prev.jd;
+    let rightJD = next.jd;
+    let iterations = 0;
+    while (iterations < maxIterations && rightJD - leftJD > dedupeEpsilonDays / 4) {
+      const m1 = leftJD + (rightJD - leftJD) / 3;
+      const m2 = rightJD - (rightJD - leftJD) / 3;
+      const d1 = Math.abs(signedShortestDiff(getLongitudeAtJd(m1), targetLongitude));
+      const d2 = Math.abs(signedShortestDiff(getLongitudeAtJd(m2), targetLongitude));
+      if (d1 <= d2) {
+        rightJD = m2;
+      } else {
+        leftJD = m1;
+      }
+      iterations++;
+    }
+
+    const candidateJD = (leftJD + rightJD) / 2;
+    const candidateAbs = Math.abs(
+      signedShortestDiff(getLongitudeAtJd(candidateJD), targetLongitude)
+    );
+    if (candidateAbs <= toleranceDeg * 2) {
+      roots.push(candidateJD);
+    }
+  }
+
+  roots.sort((a, b) => a - b);
+  const dedupedRoots = dedupeSortedRoots(roots, dedupeEpsilonDays);
+
+  const debug: OracleDebugInfo = {
+    toleranceDeg,
+    sampleStepDays: stepDays,
+    dedupeEpsilonDays,
+    sanityWarnings,
+    crossings,
+    samples: samples.map((s) => ({
+      jd: s.jd,
+      isoUtc: options.toIsoUtc ? options.toIsoUtc(s.jd) : undefined,
+      longitude: s.longitude,
+      shortestDiff: s.shortestDiff,
+      phi: s.phi,
+    })),
+  };
+
+  return { roots: dedupedRoots, debug };
+}