astro_chart 0.1.0 → 0.4.0

data/lib/astro_chart/pure.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "pure/core"
+require_relative "pure/houses"
+require_relative "pure/vsop87"
+require_relative "pure/moon"
+require_relative "pure/pluto"
+
+module AstroChart
+  # Pure-Ruby ephemeris backend (MIT-safe, zero external dependencies).
+  #
+  # Front-facing API mirrors the Swiss Ephemeris C extension (AstroChart::Ext):
+  #   Pure.julday(year, month, day, hour)      -> JD(UT) Float
+  #   Pure.calc_ut(jd_ut, planet_id)           -> apparent ecliptic longitude (deg, 0-360)
+  #   Pure.houses(jd_ut, lat, lon, hsys = "P") -> { "cusps" => [12], "ascendant" => f, "mc" => f }
+  #
+  # planet_id follows the SE convention:
+  #   SUN=0 MOON=1 MERCURY=2 VENUS=3 MARS=4 JUPITER=5 SATURN=6
+  #   URANUS=7 NEPTUNE=8 PLUTO=9 TRUE_NODE=11
+  module Pure
+    # planet_id (SE convention) -> handled by which pure module
+    VSOP87_PLANET_IDS = [0, 2, 3, 4, 5, 6, 7, 8].freeze
+    MOON_ID           = 1
+    PLUTO_ID          = 9
+    TRUE_NODE_ID      = 11
+
+    module_function
+
+    # Convert calendar date/time (UT) to Julian Day number.
+    def julday(year, month, day, hour)
+      Core.julday(year, month, day, hour)
+    end
+
+    # Apparent ecliptic longitude (degrees, [0, 360)) for the given body.
+    def calc_ut(jd_ut, planet_id)
+      case planet_id
+      when *VSOP87_PLANET_IDS
+        Vsop87.apparent_longitude(planet_id, jd_ut)
+      when MOON_ID
+        Moon.apparent_longitude(jd_ut)
+      when PLUTO_ID
+        Pluto.apparent_longitude(jd_ut)
+      when TRUE_NODE_ID
+        Moon.true_node(jd_ut)
+      else
+        raise ArgumentError,
+              "unsupported planet_id #{planet_id.inspect} " \
+              "(supported: 0-9 and 11/TRUE_NODE, SE convention)"
+      end
+    end
+
+    # House cusps + ascendant + MC. Placidus ("P") and Whole Sign ("W").
+    # hsys accepts "P"/"W" or 80/87 (ord values) to mirror the C extension's int argument.
+    def houses(jd_ut, latitude, longitude, hsys = "P")
+      case hsys
+      when "P", 80 then Houses.calc(jd_ut, latitude, longitude, "P")
+      when "W", 87 then Houses.calc(jd_ut, latitude, longitude, "W")
+      when "E", 69 then Houses.calc(jd_ut, latitude, longitude, "E")
+      when "O", 79 then Houses.calc(jd_ut, latitude, longitude, "O")
+      else
+        raise ArgumentError,
+              "unsupported house system #{hsys.inspect} " \
+              "(pure backend supports Placidus \"P\"/80, Whole Sign \"W\"/87, " \
+              "Equal \"E\"/69 and Porphyry \"O\"/79)"
+      end
+    end
+  end
+end

data/lib/astro_chart/solar_arc.rb

@@ -0,0 +1,59 @@
+require_relative "time_conversion"
+require_relative "planets"
+require_relative "synastry"
+require_relative "transits"
+
+module AstroChart
+  # Solar arc directions (太陽弧正向推運): advance every natal point by a single
+  # arc — the distance the secondary-progressed Sun has travelled since birth.
+  # Unlike secondary progressions (where each body moves at its own rate),
+  # solar arc moves the whole chart rigidly, so directed-to-natal aspects
+  # perfect at a rate of ~1° per year of life.
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   result = AstroChart::SolarArc.directions(natal, "2026-07-24")
+  #   result["arc"]              # degrees the chart has been directed (~age)
+  #   result["planets"]          # directed positions + natal-house placement
+  #   result["aspects_to_natal"] # directed→natal aspects, sorted by orb
+  module SolarArc
+    DAYS_PER_YEAR = 365.2425 # matches Progressions
+
+    SUN = "太陽"
+
+    # natal_chart: a Chart#generate result hash (its input block gives birth
+    #   date/time/timezone). target_date: "YYYY-MM-DD".
+    # orb_limit: keep only directed-to-natal aspects within this orb (default
+    #   1.0 — solar arc is slow, only near-exact contacts matter).
+    def self.directions(natal_chart, target_date, orb_limit: 1.0)
+      input = natal_chart&.dig("input")
+      if input.nil? || input["birth_date"].nil? || input["birth_time"].nil? || input["timezone"].nil?
+        raise ArgumentError, "chart has no input data (birth_date/birth_time/timezone required)"
+      end
+
+      jd_natal  = TimeConversion.to_julian_day(input["birth_date"], input["birth_time"], input["timezone"])
+      jd_target = TimeConversion.to_julian_day(target_date, input["birth_time"], input["timezone"])
+      jd_prog   = jd_natal + (jd_target - jd_natal) / DAYS_PER_YEAR # a day for a year
+
+      natal_positions = Synastry.positions_from_chart(natal_chart)
+      natal_cusps     = Synastry.cusps_from_chart(natal_chart)
+
+      natal_sun = natal_positions[SUN] || Planets.calculate_positions(jd_natal)[SUN]
+      prog_sun  = Planets.calculate_positions(jd_prog)[SUN]
+      # The Sun only ever moves forward, so the forward arc is the plain
+      # modular difference (< 360° for any human lifespan).
+      arc = (prog_sun - natal_sun) % 360.0
+
+      directed_positions = natal_positions.transform_values { |lon| (lon + arc) % 360.0 }
+
+      {
+        "arc" => arc.round(4),
+        "planets" => Transits.planet_details(directed_positions, natal_cusps),
+        "aspects_to_natal" => Transits.aspects_to_natal(
+          directed_positions, natal_positions,
+          orb_limit: orb_limit,
+          keys: %w[directed_planet natal_planet]
+        ),
+      }
+    end
+  end
+end

data/lib/astro_chart/solar_return.rb

@@ -0,0 +1,193 @@
+module AstroChart
+  # Solar return chart (太陽回歸盤): the chart cast for the exact UTC instant
+  # the transiting Sun returns to its natal longitude in a given year.
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   result = SolarReturn.for_year(natal, 2026)
+  #   result["return_jd"]       # Julian Day (UT) of the return instant
+  #   result["return_time_utc"] # ISO8601 UTC string, e.g. "2026-07-03T05:12:34Z"
+  #   result["chart"]           # full chart structure at the return instant
+  #
+  # The return instant is found by Newton iteration on the Sun's longitude,
+  # then the chart is computed directly at that Julian Day (no lossy
+  # round-trip through date strings).
+  module SolarReturn
+    SUN_ID = Ephemeris::PLANETS["太陽"]
+
+    # Raised when the Newton iteration fails to converge (should not happen
+    # for the Sun, whose longitude is monotonic at ~0.9856°/day).
+    class ConvergenceError < StandardError; end
+
+    # Convergence threshold in degrees (~0.36 arcsec, i.e. under 10 seconds
+    # of clock time at the Sun's mean speed).
+    CONVERGENCE_DEG = 1e-4
+    MAX_ITERATIONS  = 20
+
+    # Same planet => aspect-list wiring as Chart#generate.
+    ASPECT_MAP = {
+      "太陽"  => "sun_aspects",
+      "月亮"  => "moon_aspects",
+      "土星"  => "saturn_aspects",
+      "金星"  => "venus_aspects",
+      "北交點" => "north_node_aspects",
+      "南交點" => "south_node_aspects",
+    }.freeze
+
+    # Build the solar return for a natal chart (a Chart#generate hash) in the
+    # given year. Location defaults to the natal chart's coordinates/timezone;
+    # pass latitude:/longitude: (and timezone:, informational) to relocate.
+    def self.for_year(natal_chart, year, latitude: nil, longitude: nil, timezone: nil)
+      natal_sun = natal_sun_degree(natal_chart)
+      month, day = natal_month_day(natal_chart)
+
+      input = natal_chart["input"] || {}
+      coords = input["coordinates"] || {}
+      lat = latitude  || coords["latitude"]
+      lng = longitude || coords["longitude"]
+      tz  = timezone  || input["timezone"]
+      if lat.nil? || lng.nil?
+        raise ArgumentError,
+              "no coordinates: natal chart input has none and none were given"
+      end
+      lat = lat.to_f
+      lng = lng.to_f
+
+      jd = find_return_jd(natal_sun, year, month, day)
+
+      {
+        "return_jd"       => jd,
+        "return_time_utc" => jd_to_utc_iso8601(jd),
+        "location"        => {
+          "latitude"  => lat,
+          "longitude" => lng,
+          "timezone"  => tz,
+        },
+        "chart" => build_chart_at(jd, lat, lng),
+      }
+    end
+
+    # Newton iteration: find the JD(UT) nearest the birthday in `year` where
+    # the Sun's longitude equals target_deg.
+    def self.find_return_jd(target_deg, year, month, day)
+      jd = Ephemeris.julday(year, month, day, 12.0)
+
+      MAX_ITERATIONS.times do
+        delta = angle_delta(target_deg - Ephemeris.calc_ut(jd, SUN_ID))
+        return jd if delta.abs < CONVERGENCE_DEG
+
+        jd += delta / sun_speed(jd)
+      end
+
+      raise ConvergenceError,
+            "solar return did not converge within #{MAX_ITERATIONS} iterations " \
+            "(year=#{year}, target=#{target_deg})"
+    end
+
+    # Sun's longitudinal speed (deg/day) via central difference (~0.9856).
+    def self.sun_speed(jd, step = 0.05)
+      diff = angle_delta(
+        Ephemeris.calc_ut(jd + step, SUN_ID) - Ephemeris.calc_ut(jd - step, SUN_ID)
+      )
+      diff / (2.0 * step)
+    end
+
+    # Signed shortest angular difference, mapped into [-180, 180).
+    def self.angle_delta(deg)
+      (deg + 540.0) % 360.0 - 180.0
+    end
+
+    # Inverse Julian Day (Meeus, Astronomical Algorithms ch. 7):
+    # JD(UT) -> [year, month, day, hour, minute, second] in UTC.
+    # Rounded to the nearest whole second before decomposition, so
+    # 23:59:59.6 rolls over to 00:00:00 of the next day correctly.
+    def self.jd_to_utc(jd)
+      total_seconds = ((jd + 0.5) * 86_400.0).round
+      z   = total_seconds / 86_400
+      sec = total_seconds % 86_400
+
+      if z < 2_299_161 # before the Gregorian reform (1582-10-15)
+        a = z
+      else
+        alpha = ((z - 1_867_216.25) / 36_524.25).floor
+        a = z + 1 + alpha - (alpha / 4)
+      end
+
+      b = a + 1524
+      c = ((b - 122.1) / 365.25).floor
+      d = (365.25 * c).floor
+      e = ((b - d) / 30.6001).floor
+
+      day   = b - d - (30.6001 * e).floor
+      month = e < 14 ? e - 1 : e - 13
+      year  = month > 2 ? c - 4716 : c - 4715
+
+      [year, month, day, sec / 3600, (sec % 3600) / 60, sec % 60]
+    end
+
+    def self.jd_to_utc_iso8601(jd)
+      y, mo, d, h, mi, s = jd_to_utc(jd)
+      format("%04d-%02d-%02dT%02d:%02d:%02dZ", y, mo, d, h, mi, s)
+    end
+
+    # Chart structure at an exact JD — mirrors the "chart" section of
+    # Chart#generate, computed directly with Planets/Houses (Chart itself
+    # only accepts date strings, which would lose sub-minute precision).
+    def self.build_chart_at(jd, latitude, longitude)
+      cusps, ascendant = Houses.calculate(jd, latitude, longitude)
+
+      positions = Planets.calculate_positions(jd)
+      planet_details = Planets.build_details(positions, cusps)
+
+      kp = Planets.key_points_data(positions, cusps, ascendant)
+
+      planet_details.each do |planet|
+        key = ASPECT_MAP[planet["planet"]]
+        planet["aspects"] = kp[key] if key
+      end
+
+      planet_details.concat(kp["additional_points"])
+
+      houses_data = cusps.each_with_index.map do |deg, i|
+        {
+          "house_number" => i + 1,
+          "degree"       => deg.round(4),
+          "zodiac"       => Zodiac.sign_name(deg),
+        }
+      end
+
+      {
+        "ascendant" => {
+          "zodiac"       => Zodiac.sign_name(ascendant),
+          "degree"       => (ascendant % 30).round(4),
+          "total_degree" => ascendant.round(4),
+        },
+        "planets" => planet_details,
+        "houses"  => houses_data,
+      }
+    end
+
+    # Natal Sun total longitude from a Chart#generate hash.
+    def self.natal_sun_degree(chart)
+      planets = chart&.dig("chart", "planets")
+      raise ArgumentError, "chart has no planets data" if planets.nil? || planets.empty?
+
+      sun = planets.find { |p| p["planet"] == "太陽" }
+      raise ArgumentError, "chart has no 太陽 position" if sun.nil? || sun["total_degree"].nil?
+
+      sun["total_degree"]
+    end
+
+    # [month, day] of the natal birthday from a Chart#generate hash.
+    def self.natal_month_day(chart)
+      birth_date = chart&.dig("input", "birth_date")
+      raise ArgumentError, "chart has no input birth_date" if birth_date.nil?
+
+      _, month, day = birth_date.split("-").map(&:to_i)
+      raise ArgumentError, "invalid birth_date: #{birth_date.inspect}" if month.nil? || day.nil?
+
+      [month, day]
+    end
+
+    private_class_method :natal_sun_degree, :natal_month_day
+  end
+end

data/lib/astro_chart/stats.rb

@@ -0,0 +1,34 @@
+module AstroChart
+  # Element (四大元素) and modality (三大模式) distribution statistics.
+  #
+  # Both classifications follow directly from the zodiac sign a body
+  # occupies. Starting from 牡羊座, elements repeat every 4 signs
+  # (火土風水) and modalities every 3 signs (基本固定變動):
+  #
+  #   牡羊=火基本  金牛=土固定  雙子=風變動  巨蟹=水基本
+  #   獅子=火固定  處女=土變動  天秤=風基本  天蠍=水固定
+  #   射手=火變動  摩羯=土基本  水瓶=風固定  雙魚=水變動
+  module Stats
+    ELEMENTS = ["火", "土", "風", "水"].freeze
+    MODALITIES = ["基本", "固定", "變動"].freeze
+
+    # positions: { "太陽" => 123.45, ... } — the 10 classical planets
+    # (太陽..冥王星); the caller is responsible for passing only those.
+    #
+    # Returns:
+    #   { "elements"   => { "火" => n, "土" => n, "風" => n, "水" => n },
+    #     "modalities" => { "基本" => n, "固定" => n, "變動" => n } }
+    def self.elements(positions)
+      element_counts = ELEMENTS.to_h { |e| [e, 0] }
+      modality_counts = MODALITIES.to_h { |m| [m, 0] }
+
+      positions.each_value do |degree|
+        sign_index = (degree % 360).floor / 30
+        element_counts[ELEMENTS[sign_index % 4]] += 1
+        modality_counts[MODALITIES[sign_index % 3]] += 1
+      end
+
+      { "elements" => element_counts, "modalities" => modality_counts }
+    end
+  end
+end

data/lib/astro_chart/synastry.rb

@@ -0,0 +1,118 @@
+module AstroChart
+  # Synastry (合盤): cross-chart comparison between two natal charts.
+  #
+  # Pure composition of existing modules — Aspects.calculate works on any two
+  # ecliptic longitudes regardless of which chart they come from, and
+  # Houses.find_house places any longitude into any set of cusps.
+  # Backend-independent: no ephemeris call happens here.
+  #
+  # Typical usage with two Chart#generate results:
+  #
+  #   result = Synastry.between(chart_a, chart_b)
+  #   result["aspects"]               # A 的行星 × B 的行星 的跨盤相位
+  #   result["a_planets_in_b_houses"] # A 的行星落在 B 的哪一宮（疊盤）
+  #   result["b_planets_in_a_houses"] # B 的行星落在 A 的哪一宮
+  module Synastry
+    # Bodies used for cross-chart comparison.
+    # 南交點 is excluded by default: it is always exactly opposite 北交點,
+    # so including it would mirror every node aspect and double the noise.
+    BODIES = Ephemeris::PLANETS.keys.freeze
+
+    # Cross aspects between two position sets.
+    #
+    # positions_a / positions_b: { "太陽" => 123.45, ... } (ecliptic longitudes)
+    # orb_limit: optional Float — keep only aspects with orb <= limit.
+    #   (Aspects uses natal orbs: conjunction 15°, others 6-10°. Synastry
+    #   practice often uses tighter orbs; pass e.g. orb_limit: 6.0 to tighten.)
+    #
+    # Returns Array of:
+    #   { "a_planet" => "太陽", "b_planet" => "月亮",
+    #     "aspect_type" => "三分相", "orb" => 1.23 }
+    #
+    # Note: (A太陽, B月亮) and (A月亮, B太陽) are different pairs —
+    # they compare different positions, both are kept.
+    def self.cross_aspects(positions_a, positions_b, orb_limit: nil)
+      results = []
+      positions_a.each do |name_a, pos_a|
+        positions_b.each do |name_b, pos_b|
+          aspect_type, orb = Aspects.calculate(pos_a, pos_b)
+          next if aspect_type.nil?
+          next if orb_limit && orb > orb_limit
+
+          results << {
+            "a_planet"    => name_a,
+            "b_planet"    => name_b,
+            "aspect_type" => aspect_type,
+            "orb"         => orb,
+          }
+        end
+      end
+      results.sort_by { |r| r["orb"] }
+    end
+
+    # House overlay (疊盤): place one person's planets into the other
+    # person's houses.
+    #
+    # positions: { "太陽" => 123.45, ... }
+    # cusps: 12 house cusp degrees (cusps[0] = 1st house)
+    #
+    # Returns { "太陽" => 7, ... } (house number 1-12)
+    def self.house_overlay(positions, cusps)
+      positions.each_with_object({}) do |(name, pos), out|
+        house = Houses.find_house(pos, cusps)
+        out[name] = house if house
+      end
+    end
+
+    # Full synastry between two Chart#generate result hashes.
+    def self.between(chart_a, chart_b, orb_limit: nil)
+      pos_a = positions_from_chart(chart_a)
+      pos_b = positions_from_chart(chart_b)
+      cusps_a = cusps_from_chart(chart_a)
+      cusps_b = cusps_from_chart(chart_b)
+
+      {
+        "aspects"               => cross_aspects(pos_a, pos_b, orb_limit: orb_limit),
+        "a_planets_in_b_houses" => house_overlay(pos_a, cusps_b),
+        "b_planets_in_a_houses" => house_overlay(pos_b, cusps_a),
+      }
+    end
+
+    # Extract { name => total_degree } for BODIES from a Chart#generate hash.
+    # Ruler points appended by key_points_data are ignored (not in BODIES).
+    def self.positions_from_chart(chart)
+      planets = chart&.dig("chart", "planets")
+      raise ArgumentError, "chart has no planets data" if planets.nil? || planets.empty?
+
+      planets.each_with_object({}) do |p, out|
+        name = p["planet"]
+        next unless BODIES.include?(name)
+
+        degree = p["total_degree"] || total_degree_from(p)
+        out[name] = degree if degree
+      end
+    end
+
+    # Extract the 12 cusp degrees (index 0 = 1st house) from a Chart#generate hash.
+    def self.cusps_from_chart(chart)
+      houses = chart&.dig("chart", "houses")
+      raise ArgumentError, "chart has no houses data" if houses.nil? || houses.length != 12
+
+      houses.sort_by { |h| h["house_number"] }.map { |h| h["degree"] }
+    end
+
+    # Fallback for older snapshots that only stored zodiac + in-sign degree.
+    def self.total_degree_from(planet)
+      zodiac = planet["zodiac"]
+      degree = planet["degree"]
+      return nil if zodiac.nil? || degree.nil?
+
+      sign_index = Zodiac::SIGNS.index(zodiac)
+      return nil if sign_index.nil?
+
+      sign_index * 30.0 + degree
+    end
+
+    private_class_method :total_degree_from
+  end
+end

data/lib/astro_chart/transit_timing.rb

@@ -0,0 +1,186 @@
+require_relative "ephemeris"
+require_relative "aspects"
+require_relative "zodiac"
+require_relative "synastry"
+require_relative "solar_return"
+
+module AstroChart
+  # Transit timing (行運精確時點): the exact UTC instants, within a date range,
+  # when a transiting body forms an exact aspect to a natal point.
+  #
+  # Where Transits.against is a single snapshot ("what aspects hold right
+  # now?"), this answers the question people actually ask — "*when* does
+  # transiting 土星 exactly square my natal 太陽?".
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   events = AstroChart::TransitTiming.events(natal, "2026-01-01", "2026-12-31")
+  #   events.first
+  #   #=> { "transit_planet" => "土星", "natal_planet" => "太陽",
+  #   #     "aspect_type" => "四分相", "jd" => 2461...,
+  #   #     "time_utc" => "2026-03-14T07:22:10Z", "transit_zodiac" => "牡羊座",
+  #   #     "retrograde" => false }
+  #
+  # Method: each transiting body's longitude is sampled across the range at
+  # `step_days`; for every natal point and aspect angle the signed separation
+  # is bracketed where it crosses exactness, then refined by bisection (robust
+  # through retrograde stations, unlike a pure Newton step). A step where the
+  # body moves < 90° guarantees no aliasing — 1 day is safe for all bodies
+  # (the Moon moves ~13°/day).
+  module TransitTiming
+    # Transiting bodies considered (12-body set minus 南交點, mirroring
+    # Synastry/Transits — a south-node hit merely mirrors a north-node one).
+    BODIES = Synastry::BODIES
+
+    # Major aspect angles. Each non-zero, non-opposition aspect is exact at two
+    # signed separations (applying from either side); 合相/對分相 have one.
+    MAJOR = { "合相" => 0, "六分相" => 60, "四分相" => 90, "三分相" => 120, "對分相" => 180 }.freeze
+    MINOR = { "十二分相" => 30, "半四分相" => 45, "補八分相" => 135, "補十二分相" => 150 }.freeze
+
+    CONVERGENCE_DAYS = 1e-6 # ~0.1 second of clock time
+    MAX_BISECT = 60
+
+    # natal_chart: a Chart#generate result hash.
+    # start_date / end_date: "YYYY-MM-DD" (interpreted at 00:00 UT).
+    # minor: also time the minor aspects (30/45/135/150).
+    # step_days: sampling stride (default 1.0 — safe for every body).
+    # bodies: restrict transiting bodies (default all BODIES; e.g. drop "月亮"
+    #   to avoid the Moon's ~monthly hits flooding the list).
+    #
+    # Returns an Array of event hashes sorted by time (jd ascending).
+    def self.events(natal_chart, start_date, end_date, minor: false,
+                    step_days: 1.0, bodies: nil)
+      natal = Synastry.positions_from_chart(natal_chart)
+      moving = (bodies || BODIES).select { |b| Ephemeris::PLANETS.key?(b) }
+      targets = signed_targets(minor)
+
+      jd_start = date_to_jd(start_date)
+      jd_end   = date_to_jd(end_date)
+
+      events = []
+      moving.each do |body|
+        id = Ephemeris::PLANETS[body]
+        # Sample this body's longitude ONCE across the grid, then reuse the
+        # cached samples for every natal point × aspect target (calc_ut is the
+        # cost; the scan phase does zero extra ephemeris calls, only bisection
+        # refinement recomputes).
+        grid = sample_grid(id, jd_start, jd_end, step_days)
+
+        natal.each do |n_name, n_pos|
+          targets.each do |aspect_type, sep|
+            scan_grid(grid, n_pos, sep).each do |jd0, h0, jd1, h1|
+              jd = bisect(id, n_pos, sep, jd0, h0, jd1, h1)
+              events << build_event(body, id, n_name, aspect_type, jd)
+            end
+          end
+        end
+      end
+
+      dedupe(events).sort_by { |e| e["jd"] }
+    end
+
+    # [[jd, lon], ...] samples of one body from jd_start to jd_end (inclusive).
+    def self.sample_grid(id, jd_start, jd_end, step)
+      grid = []
+      jd = jd_start
+      loop do
+        jd = jd_end if jd > jd_end
+        grid << [jd, Ephemeris.calc_ut(jd, id)]
+        break if jd >= jd_end
+
+        jd += step
+      end
+      grid
+    end
+
+    # Brackets where the signed separation crosses exactness, from cached
+    # longitudes. Returns [[jd0, h0, jd1, h1], ...] for bisection.
+    def self.scan_grid(grid, natal_pos, sep)
+      brackets = []
+      grid.each_cons(2) do |(jd0, l0), (jd1, l1)|
+        h0 = SolarReturn.angle_delta(l0 - natal_pos - sep)
+        h1 = SolarReturn.angle_delta(l1 - natal_pos - sep)
+        # A sign change with both endpoints near the target (|h| < 90°) is a
+        # real crossing; the |h| guard rejects the ±180° wrap discontinuity.
+        next unless h0 != 0 && (h0 <=> 0) != (h1 <=> 0) && h0.abs < 90 && h1.abs < 90
+
+        brackets << [jd0, h0, jd1, h1]
+      end
+      brackets
+    end
+
+    # Signed separations at which each aspect is exact. 合相 (0) and 對分相
+    # (180) have a single point; the rest have ±angle.
+    def self.signed_targets(minor)
+      table = minor ? MAJOR.merge(MINOR) : MAJOR
+      table.flat_map do |name, angle|
+        if angle.zero? || angle == 180
+          [[name, angle]]
+        else
+          [[name, angle], [name, -angle]]
+        end
+      end
+    end
+
+    def self.bisect(id, natal_pos, sep, a, ha, b, _hb)
+      MAX_BISECT.times do
+        break if (b - a) < CONVERGENCE_DAYS
+
+        mid = (a + b) / 2.0
+        hm = separation(id, mid, natal_pos, sep)
+        if hm == 0
+          return mid
+        elsif (ha <=> 0) != (hm <=> 0)
+          b = mid
+        else
+          a = mid
+          ha = hm
+        end
+      end
+      (a + b) / 2.0
+    end
+
+    # Signed distance (deg, [-180,180)) from exactness of this aspect.
+    def self.separation(id, jd, natal_pos, sep)
+      SolarReturn.angle_delta(Ephemeris.calc_ut(jd, id) - natal_pos - sep)
+    end
+
+    def self.build_event(body, id, natal_name, aspect_type, jd)
+      lon = Ephemeris.calc_ut(jd, id)
+      {
+        "transit_planet" => body,
+        "natal_planet"   => natal_name,
+        "aspect_type"    => aspect_type,
+        "jd"             => jd,
+        "time_utc"       => SolarReturn.jd_to_utc_iso8601(jd),
+        "transit_zodiac" => Zodiac.sign_name(lon),
+        "retrograde"     => never_retrograde?(body) ? false : Ephemeris.retrograde?(jd, id),
+      }
+    end
+
+    def self.never_retrograde?(body)
+      body == "太陽" || body == "月亮"
+    end
+
+    # Two roots for the same contact found at adjacent brackets (a root landing
+    # on a sample boundary) collapse to one.
+    def self.dedupe(events)
+      events
+        .group_by { |e| [e["transit_planet"], e["natal_planet"], e["aspect_type"]] }
+        .flat_map do |_key, group|
+          group.sort_by { |e| e["jd"] }.chunk_while { |a, b| (b["jd"] - a["jd"]) < 1e-3 }
+               .map(&:first)
+        end
+    end
+
+    def self.date_to_jd(date)
+      y, m, d = date.split("-").map(&:to_i)
+      raise ArgumentError, "invalid date: #{date.inspect}" if y.nil? || m.nil? || d.nil?
+
+      Ephemeris.julday(y, m, d, 0.0)
+    end
+
+    private_class_method :signed_targets, :sample_grid, :scan_grid, :bisect,
+                         :separation, :build_event, :never_retrograde?,
+                         :dedupe, :date_to_jd
+  end
+end