timeprice 0.6.0 → 0.8.0

data/lib/timeprice/cli.rb

@@ -1,6 +1,20 @@
 # frozen_string_literal: true
 
-require "thor"
+begin
+  require "thor"
+rescue LoadError
+  warn <<~MSG
+    The `timeprice` CLI requires the `thor` gem, which isn't installed in
+    this environment. Install it with:
+
+        gem install thor
+
+    Library use (`require "timeprice"`) does not need thor; it's a CLI-only
+    dependency as of v0.8.0.
+  MSG
+  exit 1
+end
+
 require "json"
 require_relative "../timeprice"
 require_relative "cli/presenters/inflation"
@@ -106,8 +120,10 @@ module Timeprice
     end
 
     desc "compare AMOUNT", "Combine FX + inflation across two (year, currency) points"
-    method_option :from, type: :string, required: true, desc: "Source as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
-    method_option :to,   type: :string, required: true, desc: "Target as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :from,     type: :string,  required: true,  desc: "Source as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :to,       type: :string,  required: true,  desc: "Target as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :forecast, type: :boolean, default: false,
+                             desc: "Allow target dates past bundled data via trailing-CAGR forecast"
     def compare(amount)
       with_error_handling do
         from_tuple = parse_compare_token(options[:from], label: "--from")
@@ -115,7 +131,8 @@ module Timeprice
         result = Timeprice.compare(
           amount: parse_amount(amount),
           from: from_tuple,
-          to: to_tuple
+          to: to_tuple,
+          forecast: options[:forecast]
         )
         render Presenters::Compare.new(result)
       end
@@ -160,12 +177,12 @@ module Timeprice
       end
 
       def parse_compare_token(token, label:)
-        raise ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
+        fail ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
 
         parts = token.strip.split(/\s+/)
         unless parts.size == 2
-          raise ArgumentError,
-                "#{label} must be \"YEAR CURRENCY\" or \"CURRENCY YEAR\", got #{token.inspect}"
+          fail ArgumentError,
+               "#{label} must be \"YEAR CURRENCY\" or \"CURRENCY YEAR\", got #{token.inspect}"
         end
 
         Point.coerce(parts)

data/lib/timeprice/compare/series.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../inflation"
+require_relative "../exchange"
+require_relative "../forecast/cpi_forecaster"
+require_relative "../forecast/cagr"
+require_relative "../cpi_lookup"
+require_relative "../data_loader"
+require_relative "../point"
+require_relative "../supported"
+
+module Timeprice
+  module Compare
+    # Annual sample points for the result-card chart. Composes the same FX
+    # leg as {Compare.run} and a year-by-year measured-or-forecast CPI ratio
+    # for the destination country.
+    #
+    # Each point is `{ date: "YYYY-01", amount:, measured: }`. Forecast
+    # points additionally carry `:low` and `:high` for the ±1σ band.
+    #
+    # @api private
+    module Series
+      module_function
+
+      DEFAULT_AMOUNT = 100.0
+
+      def for(from:, to:, forecast: false, amount: DEFAULT_AMOUNT)
+        ctx = build_context(from: from, to: to, amount: amount, forecast: forecast)
+        (ctx[:from_year]..ctx[:to_year]).map { |y| point_for(y, ctx) }
+      end
+
+      def build_context(from:, to:, amount:, forecast:)
+        from_point, to_point, to_country = coerce_points(from, to)
+        data = DataLoader.load_cpi(to_country)
+        last_key, last_cpi = last_known(data)
+        last_year = Forecast::Cagr.parse(last_key).year
+
+        {
+          source_in_dest: source_amount_in_dest(amount, from_point, to_point),
+          source_cpi: CpiLookup.new(data).at(from_point.date.to_s).value.to_f,
+          lookup: CpiLookup.new(data),
+          last_year: last_year,
+          last_cpi: last_cpi,
+          from_year: Forecast::Cagr.parse(from_point.date.to_s).year,
+          to_year: Forecast::Cagr.parse(to_point.date.to_s).year,
+          stats: forecast_stats(data, last_key, forecast, to_point, last_year),
+        }
+      end
+
+      def coerce_points(from, to)
+        from_point = Point.coerce(from)
+        to_point   = Point.coerce(to)
+        to_country = Supported.country_for_currency(to_point.currency)
+        fail UnsupportedCurrency, to_point.currency unless to_country
+
+        [from_point, to_point, to_country]
+      end
+
+      def source_amount_in_dest(amount, from_point, to_point)
+        Exchange.convert(
+          amount: amount, from: from_point.currency,
+          to: to_point.currency, date: from_point.fx_anchor_date
+        ).amount
+      end
+
+      def last_known(data)
+        annual_or_monthly = Forecast::CpiForecaster.pick_series(data)
+        last_key = annual_or_monthly.keys.max_by { |k| Forecast::Cagr.parse(k) }
+        [last_key, annual_or_monthly[last_key].to_f]
+      end
+
+      def forecast_stats(data, last_key, forecast, to_point, last_year)
+        return nil unless forecast && Forecast::Cagr.parse(to_point.date.to_s).year > last_year
+
+        Forecast::Cagr.compute(
+          series: Forecast::CpiForecaster.pick_series(data),
+          last_date: last_key,
+          window_years: Forecast::CpiForecaster::DEFAULT_WINDOW_YEARS
+        )
+      end
+
+      def point_for(year, ctx)
+        if year <= ctx[:last_year]
+          measured_point(y: year, lookup: ctx[:lookup],
+                         source_in_dest: ctx[:source_in_dest], source_cpi: ctx[:source_cpi])
+        else
+          forecast_point(y: year, last_year: ctx[:last_year], last_cpi: ctx[:last_cpi],
+                         source_in_dest: ctx[:source_in_dest], source_cpi: ctx[:source_cpi],
+                         stats: ctx[:stats])
+        end
+      end
+
+      def measured_point(y:, lookup:, source_in_dest:, source_cpi:)
+        cpi_y = lookup.at(y.to_s).value.to_f
+        { date: "#{y}-01", amount: source_in_dest * (cpi_y / source_cpi), measured: true }
+      rescue DataNotFound
+        nil
+      end
+
+      def forecast_point(y:, last_year:, last_cpi:, source_in_dest:, source_cpi:, stats:)
+        yrs = y - last_year
+        mid  = last_cpi * ((1.0 + stats[:cagr])**yrs)
+        low  = last_cpi * ((1.0 + stats[:cagr] - stats[:sigma_yoy])**yrs)
+        high = last_cpi * ((1.0 + stats[:cagr] + stats[:sigma_yoy])**yrs)
+        {
+          date: "#{y}-01",
+          amount: source_in_dest * (mid / source_cpi),
+          low: source_in_dest * (low / source_cpi),
+          high: source_in_dest * (high / source_cpi),
+          measured: false,
+        }
+      end
+    end
+
+    # @see Series.for
+    def self.series_for(**)
+      Series.for(**).compact
+    end
+  end
+end

data/lib/timeprice/compare.rb

@@ -6,6 +6,8 @@ require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
 require_relative "granularity"
+require_relative "cpi_lookup"
+require_relative "compare/series"
 
 module Timeprice
   CompareResult = Data.define(
@@ -13,7 +15,8 @@ module Timeprice
     :from_currency, :from_date,
     :to_currency, :to_date,
     :country, :fx_rate, :cpi_ratio,
-    :converted_amount, :granularity
+    :converted_amount, :granularity,
+    :forecast
   )
 
   # Compare combines FX and inflation across two (currency, date) points.
@@ -28,6 +31,11 @@ module Timeprice
   #
   # If a future refactor flips the order, the regression test in
   # spec/timeprice/compare_spec.rb will fail.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.compare}. Direct
+  # references will move to `Timeprice::Internal::Compare` in a future
+  # release.
   module Compare
     module_function
 
@@ -39,22 +47,36 @@ module Timeprice
     # @param to     [Timeprice::Point, Array(String, String)] destination point
     # @return [CompareResult]
     # @raise [UnsupportedCurrency] if either currency is not in {Supported.currencies}
-    def run(amount:, from:, to:)
+    def run(amount:, from:, to:, forecast: false)
       from_point, to_point, to_country = resolve_points(from, to)
 
-      # Step 1: convert at source date into destination currency.
+      if forecast && future_target?(to_point, to_country)
+        return run_with_forecast(
+          amount: amount, from_point: from_point, to_point: to_point, to_country: to_country
+        )
+      end
+
       fx_result = Exchange.convert(
-        amount: amount,
-        from: from_point.currency,
-        to: to_point.currency,
-        date: from_point.fx_anchor_date
+        amount: amount, from: from_point.currency,
+        to: to_point.currency, date: from_point.fx_anchor_date
       )
-      converted = fx_result.amount
 
-      # Step 2: inflate that destination-currency amount from source date to
-      # destination date using destination-country CPI.
+      if from_point.date == to_point.date
+        return fx_only_result(
+          amount: amount, from_point: from_point, to_point: to_point,
+          to_country: to_country, fx_result: fx_result
+        )
+      end
+
+      measured_result(
+        amount: amount, from_point: from_point, to_point: to_point,
+        to_country: to_country, fx_result: fx_result
+      )
+    end
+
+    def measured_result(amount:, from_point:, to_point:, to_country:, fx_result:)
       infl = Inflation.adjust(
-        amount: converted,
+        amount: fx_result.amount,
         from: from_point.date.to_s,
         to: to_point.date.to_s,
         country: to_country
@@ -70,8 +92,28 @@ module Timeprice
         country: to_country,
         fx_rate: fx_result.rate,
         cpi_ratio: infl.to_index.to_f / infl.from_index,
-        converted_amount: converted,
-        granularity: Granularity.merge(fx_result.granularity, infl.granularity)
+        converted_amount: fx_result.amount,
+        granularity: Granularity.merge(fx_result.granularity, infl.granularity),
+        forecast: nil
+      )
+    end
+
+    # Same-date branch: no time-elapsed inflation, so the FX leg alone is
+    # the answer. Builds a CompareResult with cpi_ratio=1.0.
+    def fx_only_result(amount:, from_point:, to_point:, to_country:, fx_result:)
+      CompareResult.new(
+        amount: fx_result.amount,
+        original_amount: amount.to_f,
+        from_currency: from_point.currency,
+        from_date: from_point.date.to_s,
+        to_currency: to_point.currency,
+        to_date: to_point.date.to_s,
+        country: to_country,
+        fx_rate: fx_result.rate,
+        cpi_ratio: 1.0,
+        converted_amount: fx_result.amount,
+        granularity: fx_result.granularity,
+        forecast: nil
       )
     end
 
@@ -79,12 +121,63 @@ module Timeprice
     def resolve_points(from, to)
       from_point = Point.coerce(from)
       to_point   = Point.coerce(to)
-      raise UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
+      fail UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
 
       to_country = Supported.country_for_currency(to_point.currency)
-      raise UnsupportedCurrency, to_point.currency unless to_country
+      fail UnsupportedCurrency, to_point.currency unless to_country
 
       [from_point, to_point, to_country]
     end
+
+    # Returns true when to_point.date is past the destination country's last
+    # bundled CPI date.
+    def future_target?(to_point, to_country)
+      data   = DataLoader.load_cpi(to_country)
+      series = Forecast::CpiForecaster.pick_series(data)
+      last   = series.keys.max_by { |k| Forecast::Cagr.parse(k) }
+      Forecast::Cagr.parse(to_point.date.to_s) > Forecast::Cagr.parse(last)
+    end
+
+    def run_with_forecast(amount:, from_point:, to_point:, to_country:)
+      fx_result = Exchange.convert(
+        amount: amount, from: from_point.currency,
+        to: to_point.currency, date: from_point.fx_anchor_date
+      )
+      cpi_fwd          = Forecast::CpiForecaster.project(country: to_country, target: to_point.date.to_s)
+      source_cpi_value = source_index(to_country, from_point.date.to_s)
+      inflation_ratio  = cpi_fwd.value / source_cpi_value
+
+      CompareResult.new(
+        amount: fx_result.amount * inflation_ratio,
+        original_amount: amount.to_f,
+        from_currency: from_point.currency, from_date: from_point.date.to_s,
+        to_currency: to_point.currency,     to_date: to_point.date.to_s,
+        country: to_country,
+        fx_rate: fx_result.rate,
+        cpi_ratio: inflation_ratio,
+        converted_amount: fx_result.amount,
+        granularity: :forecast,
+        forecast: forecast_hash(cpi_fwd: cpi_fwd, converted: fx_result.amount, source_cpi: source_cpi_value)
+      )
+    end
+
+    def forecast_hash(cpi_fwd:, converted:, source_cpi:)
+      {
+        basis_kind: cpi_fwd.basis_kind,
+        projection_method: cpi_fwd.projection_method,
+        window_years: cpi_fwd.window_years,
+        sigma_pct: cpi_fwd.sigma_pct,
+        last_known_date: cpi_fwd.last_known_date,
+        horizon_months: cpi_fwd.horizon_months,
+        low: converted * (cpi_fwd.low / source_cpi),
+        high: converted * (cpi_fwd.high / source_cpi),
+        warnings: cpi_fwd.warnings,
+      }
+    end
+
+    # Resolve a measured CPI index for the source date (which must be in range).
+    def source_index(country, date)
+      CpiLookup.new(DataLoader.load_cpi(country)).at(date).value.to_f
+    end
   end
 end

data/lib/timeprice/cpi_lookup.rb

@@ -22,17 +22,23 @@ module Timeprice
       @annual    = data.dig("series", "annual")    || {}
     end
 
-    # @param key [String] "YYYY", "YYYY-MM", or "YYYY-Qn"
+    # @param key [String] "YYYY", "YYYY-MM", "YYYY-Qn", or "YYYY-MM-DD"
     # @return [CpiPoint]
     # @raise [DataNotFound] if no CPI value covers `key`
     # @raise [ArgumentError] on malformed `key`
+    #
+    # Daily keys are accepted and silently resolved at month grain — CPI is
+    # published monthly at best, so the day is dropped before lookup. The
+    # returned granularity reflects what the monthly cascade actually found
+    # (monthly / quarterly fallback / annual fallback), not "daily".
     def at(key)
       key = key.to_s
       case key
-      when QUARTER_RE        then quarterly_or_fallbacks(key)
-      when /\A\d{4}-\d{2}\z/ then monthly_or_fallbacks(key)
-      when /\A\d{4}\z/       then annual_or_derived(key)
-      else raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, or YYYY-Qn)"
+      when QUARTER_RE              then quarterly_or_fallbacks(key)
+      when /\A\d{4}-\d{2}-\d{2}\z/ then monthly_or_fallbacks(key[0, 7])
+      when /\A\d{4}-\d{2}\z/       then monthly_or_fallbacks(key)
+      when /\A\d{4}\z/             then annual_or_derived(key)
+      else fail ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, YYYY-Qn, or YYYY-MM-DD)"
       end
     end
 
@@ -48,7 +54,7 @@ module Timeprice
       end
 
       year_key = month_key[0, 4]
-      raise DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
+      fail DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
 
       CpiPoint.new(value: @annual[year_key], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
@@ -71,7 +77,7 @@ module Timeprice
       end
 
       year = quarter_key[0, 4]
-      raise DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
+      fail DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
 
       CpiPoint.new(value: @annual[year], granularity: Granularity::QUARTERLY_FROM_ANNUAL_FALLBACK)
     end
@@ -90,7 +96,7 @@ module Timeprice
       return average(months, months.size, Granularity::ANNUAL_FROM_PARTIAL_MONTHS) if months.any?
       return average(quarters, quarters.size, Granularity::ANNUAL_FROM_PARTIAL_QUARTERS) if quarters.any?
 
-      raise DataNotFound, missing_message(year)
+      fail DataNotFound, missing_message(year)
     end
 
     def average(series, divisor, granularity)

data/lib/timeprice/data_loader.rb

@@ -2,18 +2,13 @@
 
 require "json"
 require_relative "errors"
+require_relative "schema"
 
 module Timeprice
   # Loads and caches the bundled JSON data files. Override the search root
   # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
   # {DataLoader.data_root=}.
   module DataLoader
-    SUPPORTED_SCHEMA_VERSION = 4
-
-    # Files written by older toolchains remain readable: v3 is monthly+annual
-    # only; v4 adds an optional `series.quarterly` block.
-    SUPPORTED_SCHEMA_VERSIONS = [3, 4].freeze
-
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
@@ -46,8 +41,8 @@ module Timeprice
         manifest_cache[data_root] ||= begin
           path = File.join(data_root, "manifest.json")
           unless File.exist?(path)
-            raise DataNotFound, "manifest.json missing (looked in #{path}). " \
-                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+            fail DataNotFound, "manifest.json missing (looked in #{path}). " \
+                               "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
           end
 
           parse_with_schema(path)
@@ -64,12 +59,12 @@ module Timeprice
         key = country.to_s.downcase
         code = country.to_s.upcase
         cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless Supported.country?(code)
+          fail UnsupportedCountry, code unless Supported.country?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
-            raise DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
-                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+            fail DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
+                               "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
           end
 
           parse_with_schema(path)
@@ -84,7 +79,7 @@ module Timeprice
         key = year.to_i
         fx_cache[[data_root, key]] ||= begin
           path = File.join(data_root, "fx", "usd", "#{key}.json")
-          raise DataNotFound, "No FX data for year #{key}" unless File.exist?(path)
+          fail DataNotFound, "No FX data for year #{key}" unless File.exist?(path)
 
           parse_with_schema(path)
         end
@@ -116,11 +111,7 @@ module Timeprice
       end
 
       def parse_with_schema(path)
-        data = JSON.parse(File.read(path))
-        version = data["schema_version"]
-        raise UnsupportedSchemaVersion.new(version, path) unless SUPPORTED_SCHEMA_VERSIONS.include?(version)
-
-        data
+        Schema.load_cpi(JSON.parse(File.read(path)), path: path)
       end
     end
   end

data/lib/timeprice/date.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Timeprice
+  # Raised when a user-supplied date string can't be parsed into a
+  # {Timeprice::Date} value.
+  class InvalidDate < Error; end
+
+  # Immutable value object representing "a date at some granularity": a
+  # year, a year+month, a year+quarter, or a full calendar day. Used as
+  # the canonical input shape for the public API (`Timeprice.inflation`,
+  # `Timeprice.exchange`, `Timeprice.compare`) — strings are accepted for
+  # convenience and coerced via {.coerce} at the boundary.
+  # rubocop:disable Lint/ConstantDefinitionInBlock
+  Date = Data.define(:year, :month, :quarter, :day) do
+    ANNUAL_RE    = /\A(\d{4})\z/
+    MONTHLY_RE   = /\A(\d{4})-(\d{2})\z/
+    QUARTERLY_RE = /\A(\d{4})-Q([1-4])\z/i
+    DAILY_RE     = /\A(\d{4})-(\d{2})-(\d{2})\z/
+
+    def self.parse(str)
+      case str.to_s
+      when DAILY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: ::Regexp.last_match(2).to_i,
+            quarter: nil, day: ::Regexp.last_match(3).to_i)
+      when QUARTERLY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: nil,
+            quarter: ::Regexp.last_match(2).to_i, day: nil)
+      when MONTHLY_RE
+        new(year: ::Regexp.last_match(1).to_i, month: ::Regexp.last_match(2).to_i,
+            quarter: nil, day: nil)
+      when ANNUAL_RE
+        new(year: ::Regexp.last_match(1).to_i, month: nil, quarter: nil, day: nil)
+      else
+        fail InvalidDate, "Cannot parse #{str.inspect} as a Timeprice::Date"
+      end
+    end
+
+    def self.coerce(input)
+      input.is_a?(self) ? input : parse(input)
+    end
+
+    def granularity
+      return :daily     if day
+      return :monthly   if month
+      return :quarterly if quarter
+
+      :annual
+    end
+
+    def to_s
+      case granularity
+      when :daily     then format("%04d-%02d-%02d", year, month, day)
+      when :monthly   then format("%04d-%02d", year, month)
+      when :quarterly then format("%04d-Q%d", year, quarter)
+      else format("%04d", year)
+      end
+    end
+  end
+  # rubocop:enable Lint/ConstantDefinitionInBlock
+end

data/lib/timeprice/exchange.rb

@@ -5,6 +5,7 @@ require_relative "errors"
 require_relative "data_loader"
 require_relative "supported"
 require_relative "granularity"
+require_relative "date"
 
 module Timeprice
   ExchangeResult = Data.define(
@@ -15,6 +16,11 @@ module Timeprice
   # Handles identity (USD→USD), direct lookup, inverse, and triangulation
   # through USD. Weekend/holiday dates fall back up to {MAX_FALLBACK_DAYS}
   # days to the nearest prior trading day.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.exchange}. Direct
+  # references will move to `Timeprice::Internal::Exchange` in a future
+  # release.
   module Exchange
     BASE = "USD"
     MAX_FALLBACK_DAYS = 7
@@ -33,8 +39,8 @@ module Timeprice
     def convert(amount:, from:, to:, date:)
       from = from.to_s.upcase
       to   = to.to_s.upcase
-      raise UnsupportedCurrency, from unless Supported.currency?(from)
-      raise UnsupportedCurrency, to   unless Supported.currency?(to)
+      fail UnsupportedCurrency, from unless Supported.currency?(from)
+      fail UnsupportedCurrency, to   unless Supported.currency?(to)
 
       d = parse_date(date)
 
@@ -69,18 +75,32 @@ module Timeprice
         rate, eff, gran = lookup_usd_base(from, d)
         [1.0 / rate, eff, gran]
       else
-        # Triangulation: from → USD → to, both legs at the same effective date.
-        usd_to_from, eff_a, gran_a = lookup_usd_base(from, d)
-        usd_to_to,   eff_b, gran_b = lookup_usd_base(to,   d)
-        if eff_a != eff_b
-          raise DataNotFound,
-                "FX triangulation date mismatch for #{from}->#{to} on #{d}: " \
-                "USD->#{from} resolved #{eff_a}, USD->#{to} resolved #{eff_b}"
-        end
-        [usd_to_to / usd_to_from, eff_a, Granularity.merge(gran_a, gran_b)]
+        # Triangulation: from → USD → to. Daily legs must agree on the
+        # effective date; an annual leg is valid for any date in its year, so
+        # we adopt the daily leg's date and let Granularity.merge demote.
+        rate_a, *leg_a = lookup_usd_base(from, d)
+        rate_b, *leg_b = lookup_usd_base(to,   d)
+        eff = reconcile_triangulation_dates(from, to, d, leg_a, leg_b)
+        [rate_b / rate_a, eff, Granularity.merge(leg_a[1], leg_b[1])]
       end
     end
 
+    # Pick a single effective date for a triangulated rate. Daily legs must
+    # agree; an annual leg is year-wide so it adopts the daily leg's date.
+    # When both legs are annual we fall back to the requested date.
+    def reconcile_triangulation_dates(from, to, d, leg_a, leg_b)
+      eff_a, gran_a = leg_a
+      eff_b, gran_b = leg_b
+      return eff_a if eff_a == eff_b
+      return d     if gran_a == Granularity::ANNUAL && gran_b == Granularity::ANNUAL
+      return eff_b if gran_a == Granularity::ANNUAL
+      return eff_a if gran_b == Granularity::ANNUAL
+
+      fail DataNotFound,
+           "FX triangulation date mismatch for #{from}->#{to} on #{d}: " \
+           "USD->#{from} resolved #{eff_a}, USD->#{to} resolved #{eff_b}"
+    end
+
     # Walk back up to MAX_FALLBACK_DAYS to find a daily rate; if none, fall
     # back to data/fx/usd/_annual.json (the single source of annual FX truth).
     # Returns [rate, effective_date, granularity].
@@ -105,7 +125,7 @@ module Timeprice
       annual_rate = annual_fallback(currency, d.year)
       return [annual_rate, d, Granularity::ANNUAL] if annual_rate
 
-      raise DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
+      fail DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
     end
 
     # Consult data/fx/usd/_annual.json. Returns Float or nil.
@@ -118,20 +138,26 @@ module Timeprice
 
     def parse_date(date)
       case date
-      when Date then date
+      when ::Date
+        date
+      when Timeprice::Date
+        require_daily!(date)
+        ::Date.new(date.year, date.month, date.day)
       when String
-        unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
-          raise ArgumentError, "Invalid date format: #{date.inspect} (use YYYY-MM-DD)"
-        end
-
-        begin
-          Date.parse(date)
-        rescue Date::Error
-          raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
-        end
+        parsed = Timeprice::Date.coerce(date)
+        require_daily!(parsed)
+        ::Date.new(parsed.year, parsed.month, parsed.day)
       else
-        raise ArgumentError, "Invalid date: #{date.inspect}"
+        fail ArgumentError, "Invalid date: #{date.inspect}"
       end
+    rescue ::Date::Error
+      raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
+    end
+
+    def require_daily!(date)
+      return if date.granularity == :daily
+
+      fail ArgumentError, "Invalid date: Exchange needs YYYY-MM-DD, got #{date}"
     end
   end
 end