astro_chart 0.2.0 → 0.4.0

data/lib/astro_chart/ephemeris.rb

@@ -3,45 +3,28 @@
 module AstroChart
   DEFAULT_BACKEND = :pure
 
+  # Backend selection lives on Ephemeris (not the AstroChart top-level
+  # constant) so host apps that reassign or remove the AstroChart constant
+  # (e.g. a Rails app whose ActiveRecord model claims the name after
+  # capturing the gem classes) never break internal dispatch.
+  # AstroChart.backend / backend= below stay as thin delegators for
+  # API compatibility.
   class << self
     # Current ephemeris backend (:pure or :swiss). Defaults to :pure.
     def backend
-      @backend ||= DEFAULT_BACKEND
+      Ephemeris.backend
     end
 
     # Switch the ephemeris backend.
     #
     #   AstroChart.backend = :pure   # pure-Ruby (default, no C extension needed)
     #   AstroChart.backend = :swiss  # Swiss Ephemeris C extension (AGPL)
-    #
-    # Selecting :swiss loads the C extension on demand; a missing/uncompiled
-    # extension raises LoadError with an explicit message instead of failing
-    # silently at call time.
     def backend=(name)
-      case name
-      when :pure
-        @backend = :pure
-      when :swiss
-        load_swiss_extension!
-        @backend = :swiss
-      else
-        raise ArgumentError,
-              "unknown backend #{name.inspect} (expected :pure or :swiss)"
-      end
+      Ephemeris.backend = name
     end
 
     def load_swiss_extension!
-      return if defined?(AstroChart::Ext)
-
-      begin
-        require_relative "astro_chart_ext"
-      rescue LoadError => e
-        raise LoadError,
-              "AstroChart :swiss backend requires the compiled Swiss Ephemeris C extension " \
-              "(astro_chart_ext). Build it with `rake compile` (or `ruby ext/astro_chart/extconf.rb && make`), " \
-              "or use the default pure-Ruby backend (AstroChart.backend = :pure). " \
-              "Original error: #{e.message}"
-      end
+      Ephemeris.load_swiss_extension!
     end
   end
 
@@ -49,6 +32,43 @@ module AstroChart
   # module so the backend (:pure / :swiss) can be swapped without touching
   # the rest of the code.
   module Ephemeris
+    class << self
+      # Current ephemeris backend (:pure or :swiss). Defaults to :pure.
+      def backend
+        @backend ||= DEFAULT_BACKEND
+      end
+
+      # Selecting :swiss loads the C extension on demand; a missing/uncompiled
+      # extension raises LoadError with an explicit message instead of failing
+      # silently at call time.
+      def backend=(name)
+        case name
+        when :pure
+          @backend = :pure
+        when :swiss
+          load_swiss_extension!
+          @backend = :swiss
+        else
+          raise ArgumentError,
+                "unknown backend #{name.inspect} (expected :pure or :swiss)"
+        end
+      end
+
+      def load_swiss_extension!
+        return if defined?(Ext)
+
+        begin
+          require_relative "astro_chart_ext"
+        rescue LoadError => e
+          raise LoadError,
+                "AstroChart :swiss backend requires the compiled Swiss Ephemeris C extension " \
+                "(astro_chart_ext). Build it with `rake compile` (or `ruby ext/astro_chart/extconf.rb && make`), " \
+                "or use the default pure-Ruby backend (AstroChart.backend = :pure). " \
+                "Original error: #{e.message}"
+        end
+      end
+    end
+
     # SE-convention planet ids (numeric literals so the :pure default
     # works without the C extension loaded; values match AstroChart::Ext
     # constants when the extension is present).
@@ -68,7 +88,7 @@ module AstroChart
 
     # Convert date/time to Julian Day number.
     def self.julday(year, month, day, hour)
-      case AstroChart.backend
+      case backend
       when :swiss then Ext.julday(year, month, day, hour)
       else Pure.julday(year, month, day, hour)
       end
@@ -76,16 +96,45 @@ module AstroChart
 
     # Calculate planet apparent ecliptic longitude (degrees 0-360).
     def self.calc_ut(jd, planet_id)
-      case AstroChart.backend
+      case backend
       when :swiss then Ext.calc_ut(jd, planet_id)
       else Pure.calc_ut(jd, planet_id)
       end
     end
 
+    # Apparent daily motion in ecliptic longitude (degrees/day), via central
+    # difference of calc_ut at jd ± 0.5 day. The difference is folded into
+    # (-180, 180] so the 0°/360° wraparound never produces a spurious value.
+    # Negative speed = retrograde motion.
+    #
+    # When jd ± 0.5 falls outside a body's valid ephemeris window (e.g. the
+    # pure Pluto series' 1885-2099 range) while jd itself is inside, the
+    # stencil falls back to a one-sided difference over half a day, so
+    # charts at the very edges of the documented range still work. A jd
+    # that is itself out of range still raises Pure::Core::DomainError.
+    def self.speed(jd, planet_id)
+      a, b, days =
+        begin
+          [calc_ut(jd - 0.5, planet_id), calc_ut(jd + 0.5, planet_id), 1.0]
+        rescue Pure::Core::DomainError
+          begin
+            [calc_ut(jd, planet_id), calc_ut(jd + 0.5, planet_id), 0.5]
+          rescue Pure::Core::DomainError
+            [calc_ut(jd - 0.5, planet_id), calc_ut(jd, planet_id), 0.5]
+          end
+        end
+      (((b - a + 540.0) % 360.0) - 180.0) / days
+    end
+
+    # Whether the body is retrograde (moving backwards in longitude) at jd.
+    def self.retrograde?(jd, planet_id)
+      speed(jd, planet_id) < 0
+    end
+
     # Calculate house cusps + ascendant.
     # Returns { "cusps" => [12 floats], "ascendant" => float, "mc" => float }
     def self.houses(jd, latitude, longitude, system = "P")
-      case AstroChart.backend
+      case backend
       when :swiss then Ext.houses(jd, latitude, longitude, system.ord)
       else Pure.houses(jd, latitude, longitude, system)
       end

data/lib/astro_chart/houses.rb

@@ -1,8 +1,9 @@
 module AstroChart
   module Houses
     # Calculate house cusps and ascendant from Julian Day + coordinates.
+    # system: "P" (Placidus, default) or "W" (Whole Sign).
     # Returns [cusps_array(12), ascendant_degree].
-    def self.calculate(jd, latitude, longitude, system = "P")
+    def self.calculate(jd, latitude, longitude, system: "P")
       data = Ephemeris.houses(jd, latitude, longitude, system)
       [data["cusps"], data["ascendant"]]
     end

data/lib/astro_chart/lunar_return.rb

@@ -0,0 +1,90 @@
+require_relative "ephemeris"
+require_relative "solar_return"
+
+module AstroChart
+  # Lunar return chart (月亮回歸盤): the chart cast for the exact UTC instant the
+  # transiting Moon returns to its natal longitude — a monthly (~27.32-day)
+  # cycle, the lunar analogue of the solar return.
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   result = AstroChart::LunarReturn.for_date(natal, "2026-07-24")
+  #   result["return_jd"]       # Julian Day (UT) of the nearest return
+  #   result["return_time_utc"] # ISO8601 UTC
+  #   result["chart"]           # full chart at the return instant
+  #
+  # The instant is found by Newton iteration on the Moon's longitude starting
+  # from the target date, so it converges to the return nearest that date
+  # (within ~±½ cycle). Chart building and JD↔UTC reuse SolarReturn.
+  module LunarReturn
+    MOON_ID = Ephemeris::PLANETS["月亮"]
+
+    class ConvergenceError < StandardError; end
+
+    CONVERGENCE_DEG = 1e-4
+    MAX_ITERATIONS  = 40 # more than the Sun: the Moon's speed varies ~11-15°/day
+
+    # natal_chart: a Chart#generate result hash. target_date: "YYYY-MM-DD" —
+    # the returned instant is the lunar return nearest this date.
+    # Location defaults to the natal coordinates; pass latitude:/longitude:
+    # (and timezone:, informational) to relocate.
+    def self.for_date(natal_chart, target_date, latitude: nil, longitude: nil, timezone: nil)
+      natal_moon = natal_moon_degree(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
+
+      jd = find_return_jd(natal_moon, target_date)
+
+      {
+        "return_jd"       => jd,
+        "return_time_utc" => SolarReturn.jd_to_utc_iso8601(jd),
+        "location"        => { "latitude" => lat.to_f, "longitude" => lng.to_f, "timezone" => tz },
+        "chart"           => SolarReturn.build_chart_at(jd, lat.to_f, lng.to_f),
+      }
+    end
+
+    # Newton iteration on the Moon's longitude from the target date.
+    def self.find_return_jd(target_deg, target_date)
+      y, m, d = target_date.split("-").map(&:to_i)
+      raise ArgumentError, "invalid date: #{target_date.inspect}" if y.nil? || m.nil? || d.nil?
+
+      jd = Ephemeris.julday(y, m, d, 0.0)
+
+      MAX_ITERATIONS.times do
+        delta = SolarReturn.angle_delta(target_deg - Ephemeris.calc_ut(jd, MOON_ID))
+        return jd if delta.abs < CONVERGENCE_DEG
+
+        jd += delta / moon_speed(jd)
+      end
+
+      raise ConvergenceError,
+            "lunar return did not converge within #{MAX_ITERATIONS} iterations " \
+            "(date=#{target_date}, target=#{target_deg})"
+    end
+
+    # Moon's longitudinal speed (deg/day) via central difference (~13.2).
+    def self.moon_speed(jd, step = 0.02)
+      SolarReturn.angle_delta(
+        Ephemeris.calc_ut(jd + step, MOON_ID) - Ephemeris.calc_ut(jd - step, MOON_ID)
+      ) / (2.0 * step)
+    end
+
+    def self.natal_moon_degree(chart)
+      planets = chart&.dig("chart", "planets")
+      raise ArgumentError, "chart has no planets data" if planets.nil? || planets.empty?
+
+      moon = planets.find { |p| p["planet"] == "月亮" }
+      raise ArgumentError, "chart has no 月亮 position" if moon.nil? || moon["total_degree"].nil?
+
+      moon["total_degree"]
+    end
+
+    private_class_method :natal_moon_degree
+  end
+end

data/lib/astro_chart/patterns.rb

@@ -0,0 +1,248 @@
+require_relative "aspects"
+require_relative "zodiac"
+
+module AstroChart
+  # Aspect pattern detection (相位圖形).
+  #
+  # Detects the classic configurations from a set of ecliptic longitudes
+  # (相位由 Aspects.calculate 重新計算，不依賴外部相位表):
+  #
+  #   大三角 (Grand Trine): 3 bodies pairwise in 三分相.
+  #   T三角  (T-Square):    2 bodies in 對分相, both 四分相 to an apex.
+  #   大十字 (Grand Cross): 4 bodies forming 2 對分相 pairs with all 4
+  #                         adjacent pairs in 四分相.
+  #   上帝之指 (Yod):       2 bodies in 六分相, both 補十二分相 (150°) to an apex.
+  #   風箏 (Kite):          a 大三角 plus a 4th body opposing one leg and
+  #                         六分相 to the other two.
+  #   神祕矩形 (Mystic Rectangle): 2 對分相 pairs joined by 六分相 (short sides)
+  #                         and 三分相 (long sides).
+  #   星群 (Stellium):      3+ bodies sharing one zodiac sign.
+  #
+  # Deduplication rules:
+  #   - A 大十字 subsumes the 4 T三角s formed by its own bodies — those
+  #     T三角s are not reported separately.
+  #   - 南交點 sits exactly 180° from 北交點, so an opposition squared by
+  #     the node axis would always yield two mirrored T三角s (apex 北交點
+  #     and apex 南交點). The 南交點-apex twin is collapsed: the single
+  #     physical configuration is reported once, with apex 北交點.
+  #   - Each pattern is reported once regardless of body order.
+  #   - A 風箏 does NOT subsume its 大三角 — astrologers describe the two
+  #     together ("a grand trine with a kite"), so both are reported.
+  module Patterns
+    # Elements repeat every 4 signs starting from 牡羊座 (火).
+    ELEMENTS = ["火", "土", "風", "水"].freeze
+
+    # 北交點/南交點 are always exactly 180° apart by definition, so their
+    # mutual 對分相 carries no astrological information. That specific pair
+    # is therefore excluded from serving as the opposition leg of a T三角,
+    # 大十字, 神祕矩形 or 風箏. The nodes themselves remain valid participants
+    # — e.g. a node may still be the apex of a T三角, or oppose a planet.
+    NODE_AXIS = ["北交點", "南交點"].sort.freeze
+
+    # positions: { "太陽" => 123.45, ... } (ecliptic longitudes, degrees)
+    #
+    # Returns Array of:
+    #   { "pattern_type" => "大三角",   "planets" => [...], "element" => "火" | nil }
+    #   { "pattern_type" => "T三角",    "planets" => [...], "apex" => "火星" }
+    #   { "pattern_type" => "大十字",   "planets" => [...] }
+    #   { "pattern_type" => "上帝之指", "planets" => [...], "apex" => "火星" }
+    #   { "pattern_type" => "風箏",     "planets" => [...], "apex" => "火星" }
+    #   { "pattern_type" => "神祕矩形", "planets" => [...] }
+    #   { "pattern_type" => "星群",     "planets" => [...], "zodiac" => "牡羊座" }
+    def self.detect(positions)
+      names = positions.keys
+      sextiles = {}
+      trines = {}
+      squares = {}
+      oppositions = {}
+      quincunxes = {}
+
+      names.combination(2) do |a, b|
+        # minor: true so 補十二分相 (150°) is available for Yod detection;
+        # the major classifications are unaffected (major always wins).
+        type, _orb = Aspects.calculate(positions[a], positions[b], minor: true)
+        case type
+        when "六分相"     then sextiles[[a, b].sort] = true
+        when "三分相"     then trines[[a, b].sort] = true
+        when "四分相"     then squares[[a, b].sort] = true
+        when "對分相"     then oppositions[[a, b].sort] = true
+        when "補十二分相" then quincunxes[[a, b].sort] = true
+        end
+      end
+
+      # See NODE_AXIS: the definitional node opposition never counts as
+      # the opposition leg of a T三角, 大十字, 神祕矩形 or 風箏.
+      oppositions.delete(NODE_AXIS)
+
+      grand_trines = detect_grand_trines(names, trines, positions)
+      grand_crosses = detect_grand_crosses(oppositions, squares)
+      t_squares = detect_t_squares(names, oppositions, squares)
+
+      # 大十字 subsumes its own 4 T三角s.
+      cross_sets = grand_crosses.map { |gc| gc["planets"] }
+      t_squares = t_squares.reject do |t|
+        cross_sets.any? { |set| (t["planets"] - set).empty? }
+      end
+
+      # See NODE_AXIS: a 南交點-apex T三角 mirroring a 北交點-apex one on
+      # the same opposition is the same physical configuration ("opposition
+      # squared by the node axis") — report it once, with apex 北交點.
+      t_squares = t_squares.reject do |t|
+        t["apex"] == "南交點" &&
+          t_squares.any? do |other|
+            other["apex"] == "北交點" && other["planets"][0, 2] == t["planets"][0, 2]
+          end
+      end
+
+      yods = detect_yods(names, sextiles, quincunxes)
+      kites = detect_kites(grand_trines, names, oppositions, sextiles)
+      rectangles = detect_mystic_rectangles(oppositions, sextiles, trines)
+      stelliums = detect_stelliums(positions)
+
+      grand_trines + t_squares + grand_crosses +
+        yods + kites + rectangles + stelliums
+    end
+
+    def self.detect_grand_trines(names, trines, positions)
+      names.combination(3).each_with_object([]) do |(a, b, c), out|
+        next unless pair?(trines, a, b) && pair?(trines, a, c) && pair?(trines, b, c)
+
+        elements = [a, b, c].map { |n| element_of(positions[n]) }
+        out << {
+          "pattern_type" => "大三角",
+          "planets"      => [a, b, c],
+          "element"      => elements.uniq.length == 1 ? elements.first : nil,
+        }
+      end
+    end
+
+    def self.detect_t_squares(names, oppositions, squares)
+      oppositions.keys.each_with_object([]) do |(a, b), out|
+        names.each do |apex|
+          next if apex == a || apex == b
+          next unless pair?(squares, apex, a) && pair?(squares, apex, b)
+
+          out << {
+            "pattern_type" => "T三角",
+            "planets"      => [a, b, apex],
+            "apex"         => apex,
+          }
+        end
+      end
+    end
+
+    def self.detect_grand_crosses(oppositions, squares)
+      found = {}
+      oppositions.keys.combination(2) do |(a, b), (c, d)|
+        next unless ([a, b] & [c, d]).empty?
+        next unless pair?(squares, a, c) && pair?(squares, a, d) &&
+                    pair?(squares, b, c) && pair?(squares, b, d)
+
+        found[[a, b, c, d].sort] ||= {
+          "pattern_type" => "大十字",
+          "planets"      => [a, b, c, d],
+        }
+      end
+      found.values
+    end
+
+    # 上帝之指 (Yod): a 六分相 base whose two ends both point 補十二分相
+    # (150°) at a common apex. A given trio admits at most one apex, so
+    # keying by the sorted trio dedups fully.
+    def self.detect_yods(names, sextiles, quincunxes)
+      found = {}
+      sextiles.keys.each do |(a, b)|
+        names.each do |apex|
+          next if apex == a || apex == b
+          next unless pair?(quincunxes, apex, a) && pair?(quincunxes, apex, b)
+
+          found[[a, b, apex].sort] ||= {
+            "pattern_type" => "上帝之指",
+            "planets"      => [a, b, apex],
+            "apex"         => apex,
+          }
+        end
+      end
+      found.values
+    end
+
+    # 風箏 (Kite): a 大三角 plus a focal body that 對分相 one leg and 六分相
+    # the other two. Reported alongside the underlying 大三角, not instead
+    # of it.
+    def self.detect_kites(grand_trines, names, oppositions, sextiles)
+      found = {}
+      grand_trines.each do |gt|
+        trine = gt["planets"]
+        names.each do |focus|
+          next if trine.include?(focus)
+
+          trine.each do |opposed|
+            others = trine - [opposed]
+            next unless pair?(oppositions, focus, opposed)
+            next unless pair?(sextiles, focus, others[0]) &&
+                        pair?(sextiles, focus, others[1])
+
+            found[(trine + [focus]).sort] ||= {
+              "pattern_type" => "風箏",
+              "planets"      => trine + [focus],
+              "apex"         => focus,
+            }
+          end
+        end
+      end
+      found.values
+    end
+
+    # 神祕矩形 (Mystic Rectangle): two 對分相 pairs whose cross-connections
+    # are 六分相 (short sides) and 三分相 (long sides). The node-axis
+    # opposition is already excluded (see NODE_AXIS).
+    def self.detect_mystic_rectangles(oppositions, sextiles, trines)
+      found = {}
+      oppositions.keys.combination(2) do |(a, b), (c, d)|
+        next unless ([a, b] & [c, d]).empty?
+
+        ok = (pair?(sextiles, a, c) && pair?(sextiles, b, d) &&
+              pair?(trines, a, d) && pair?(trines, b, c)) ||
+             (pair?(sextiles, a, d) && pair?(sextiles, b, c) &&
+              pair?(trines, a, c) && pair?(trines, b, d))
+        next unless ok
+
+        found[[a, b, c, d].sort] ||= {
+          "pattern_type" => "神祕矩形",
+          "planets"      => [a, b, c, d],
+        }
+      end
+      found.values
+    end
+
+    # 星群 (Stellium): 3+ bodies occupying a single zodiac sign. Planet
+    # order within a sign follows the input order.
+    def self.detect_stelliums(positions)
+      by_sign = {}
+      positions.each do |name, deg|
+        (by_sign[Zodiac.sign_name(deg)] ||= []) << name
+      end
+      by_sign.select { |_sign, members| members.length >= 3 }
+             .map do |sign, members|
+        {
+          "pattern_type" => "星群",
+          "planets"      => members,
+          "zodiac"       => sign,
+        }
+      end
+    end
+
+    def self.pair?(store, a, b)
+      store.key?([a, b].sort)
+    end
+
+    def self.element_of(degree)
+      ELEMENTS[((degree % 360).floor / 30) % 4]
+    end
+
+    private_class_method :detect_grand_trines, :detect_t_squares,
+                         :detect_grand_crosses, :detect_yods, :detect_kites,
+                         :detect_mystic_rectangles, :detect_stelliums,
+                         :pair?, :element_of
+  end
+end

data/lib/astro_chart/points.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "houses"
+
+module AstroChart
+  # Derived chart points that are not physical bodies:
+  # 福點 (Part of Fortune) and 莉莉絲 (mean Black Moon Lilith / mean lunar apogee).
+  module Points
+    # Part of Fortune (福點), ecliptic longitude in degrees 0-360.
+    #
+    # Day chart:   ASC + Moon - Sun
+    # Night chart: ASC - Moon + Sun
+    def self.fortune(asc:, sun:, moon:, day_chart:)
+      longitude = day_chart ? asc + moon - sun : asc - moon + sun
+      longitude % 360.0
+    end
+
+    # Whether the chart is a day birth: the Sun is above the horizon,
+    # i.e. the Sun falls in houses 7-12 for the given house cusps.
+    # Returns nil when the Sun cannot be placed (nil/empty inputs).
+    #
+    # Note: this matches the horizon only for quadrant systems whose cusp 1
+    # is the ascendant (e.g. Placidus). For sect determination independent
+    # of the display house system, use .day_chart_from_horizon? instead.
+    def self.day_chart?(sun_longitude, cusps)
+      house = Houses.find_house(sun_longitude, cusps)
+      return nil if house.nil?
+
+      house >= 7
+    end
+
+    # Whether the chart is a day birth, judged directly from the horizon
+    # (ASC–DSC axis): the Sun is above the horizon when its ecliptic
+    # longitude lies in the half-circle from the descendant (ASC + 180°)
+    # forward to the ascendant — equivalent to quadrant houses 7-12.
+    # Sect is an astronomical fact, so this is independent of the display
+    # house system. Returns nil when either input is missing.
+    def self.day_chart_from_horizon?(sun_longitude, ascendant)
+      return nil if sun_longitude.nil? || ascendant.nil?
+
+      ((sun_longitude - ascendant) % 360.0) >= 180.0
+    end
+
+    # Antiscion (映點): the reflection of an ecliptic longitude across the
+    # Cancer–Capricorn solstice axis (0° 巨蟹 / 0° 摩羯). Two points are in
+    # antiscia when they are equidistant from that axis and thus receive the
+    # same amount of daylight; classically read as a hidden conjunction.
+    #
+    #   antiscion = (180 − L) mod 360
+    #
+    # e.g. 15° 牡羊 (L=15) → 15° 處女 (165); a point on the axis maps to itself.
+    def self.antiscion(longitude)
+      (180.0 - longitude) % 360.0
+    end
+
+    # Contra-antiscion (反映點): reflection across the Aries–Libra equinox
+    # axis (0° 牡羊 / 0° 天秤) — the antiscion's opposite point.
+    #
+    #   contra_antiscion = (360 − L) mod 360
+    def self.contra_antiscion(longitude)
+      (360.0 - longitude) % 360.0
+    end
+
+    # Mean Black Moon Lilith (莉莉絲): ecliptic longitude of the mean lunar
+    # apogee, degrees 0-360, for a given Julian Day (UT).
+    #
+    # Uses the mean longitude of the lunar perigee polynomial (Meeus,
+    # "Astronomical Algorithms", mean elements of the lunar orbit) + 180°.
+    # T is measured in Julian centuries from J2000.0. The TT-UT difference
+    # is ignored: the apogee moves ~0.111°/day, so delta-T contributes well
+    # under 0.001° in 1900-2100.
+    def self.lilith(jd)
+      t = (jd - 2451545.0) / 36525.0
+      perigee = 83.3532465 +
+                4069.0137287 * t -
+                0.0103200 * t**2 -
+                t**3 / 80_053.0 +
+                t**4 / 18_999_000.0
+      (perigee + 180.0) % 360.0
+    end
+  end
+end

data/lib/astro_chart/profection.rb

@@ -0,0 +1,56 @@
+require "date"
+require_relative "zodiac"
+require_relative "dignities"
+
+module AstroChart
+  # Annual profection (小限法) — the traditional time-lord technique where each
+  # completed year of life advances the point of emphasis by one whole sign
+  # from the ascendant. Age 0 activates the 1st house (the ASC sign), age 1 the
+  # 2nd, and so on, cycling every 12 years. The traditional ruler of the
+  # profected sign is the Lord of the Year (年主星), the year's principal
+  # significator.
+  #
+  # Pure arithmetic on the ascendant longitude and an age in whole years.
+  module Profection
+    module_function
+
+    # ascendant: ecliptic longitude of the ASC (degrees, 0-360)
+    # age:        completed years of life (integer ≥ 0)
+    #
+    # Returns:
+    #   { "age" => 36, "profected_house" => 1, "profected_sign" => "牡羊座",
+    #     "year_lord" => "火星" }
+    def annual(ascendant, age)
+      raise ArgumentError, "age must be a non-negative integer" if age.nil? || age < 0
+
+      asc_sign_index = (ascendant % 360).floor / 30
+      steps = age % 12
+      sign = Zodiac::SIGNS[(asc_sign_index + steps) % 12]
+
+      {
+        "age"             => age,
+        "profected_house" => steps + 1,
+        "profected_sign"  => sign,
+        "year_lord"       => Dignities::DOMICILE[sign],
+      }
+    end
+
+    # Convenience: derive the age (completed years) from birth and target dates
+    # (each a "YYYY-MM-DD" string or Date) and profect.
+    def at(ascendant, birth_date, target_date)
+      annual(ascendant, completed_years(to_date(birth_date), to_date(target_date)))
+    end
+
+    # Whole years elapsed from birth to target (the person's age).
+    def completed_years(birth, target)
+      years = target.year - birth.year
+      had_birthday = (target.month > birth.month) ||
+                     (target.month == birth.month && target.day >= birth.day)
+      had_birthday ? years : years - 1
+    end
+
+    def to_date(value)
+      value.is_a?(Date) ? value : Date.parse(value)
+    end
+  end
+end