timeprice 0.3.0 → 0.4.0

data/data/fx/usd/2025.json

@@ -1,5 +1,9 @@
 {
+  "schema_version": 2,
   "base": "USD",
+  "year": 2025,
+  "source": "Frankfurter (ECB) — daily reference rates",
+  "updated_at": "2026-05-11",
   "rates": {
     "2025-01-02": {
       "EUR": 0.9689,
@@ -1276,9 +1280,5 @@
       "GBP": 0.74264,
       "JPY": 156.67
     }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
-  "year": 2025
+  }
 }

data/data/fx/usd/2026.json

@@ -1,5 +1,9 @@
 {
+  "schema_version": 2,
   "base": "USD",
+  "year": 2026,
+  "source": "Frankfurter (ECB) — daily reference rates",
+  "updated_at": "2026-05-11",
   "rates": {
     "2026-01-02": {
       "EUR": 0.85317,
@@ -441,9 +445,5 @@
       "GBP": 0.73472,
       "JPY": 156.76
     }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
-  "year": 2026
+  }
 }

data/lib/timeprice/cli/presenters/compare.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../formatting"
+require_relative "../../granularity"
 
 module Timeprice
   class CLI < Thor
@@ -35,7 +36,8 @@ module Timeprice
             "#{final}  in #{@result.to_date}",
             "  #{original} (#{@result.from_date})",
             format("    -> %-#{width}s -> %s (%s)", step1, converted, @result.from_date),
-            format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date, @result.granularity),
+            format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date,
+                   Granularity.humanize(@result.granularity)),
           ]
         end
       end

data/lib/timeprice/cli/presenters/inflation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../formatting"
+require_relative "../../granularity"
 
 module Timeprice
   class CLI < Thor
@@ -27,7 +28,7 @@ module Timeprice
             format("  %s %s (%s) -> %s %s (%s)",
                    fmt_money(@result.original_amount, @ccy), @ccy, @result.from,
                    fmt_money(@result.amount, @ccy), @ccy, @result.to),
-            "  #{@result.country} · #{@result.granularity} CPI",
+            "  #{@result.country} · #{Granularity.humanize(@result.granularity)} CPI",
           ]
         end
       end

data/lib/timeprice/compare.rb

@@ -5,6 +5,7 @@ require_relative "supported"
 require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
+require_relative "granularity"
 
 module Timeprice
   CompareResult = Data.define(
@@ -70,7 +71,7 @@ module Timeprice
         fx_rate: fx_result.rate,
         cpi_ratio: infl.to_index.to_f / infl.from_index,
         converted_amount: converted,
-        granularity: infl.granularity
+        granularity: Granularity.merge(fx_result.granularity, infl.granularity)
       )
     end
 

data/lib/timeprice/cpi_lookup.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "granularity"
 
 module Timeprice
   # CpiPoint pairs a CPI index value with the granularity of how it was
-  # resolved (monthly, annual, or annual derived by averaging 12 months).
+  # resolved. See {Granularity} for the full set of possible tags.
   CpiPoint = Data.define(:value, :granularity)
 
   # Resolves CPI keys ("YYYY" or "YYYY-MM") to a CpiPoint against a single
@@ -33,21 +34,22 @@ module Timeprice
     private
 
     def monthly_or_annual_fallback(month_key)
-      return CpiPoint.new(value: @monthly[month_key], granularity: :monthly) if @monthly.key?(month_key)
+      return CpiPoint.new(value: @monthly[month_key], granularity: Granularity::MONTHLY) if @monthly.key?(month_key)
 
       year = month_key[0, 4]
       raise DataNotFound, missing_message(month_key) unless @annual.key?(year)
 
-      CpiPoint.new(value: @annual[year], granularity: :annual)
+      CpiPoint.new(value: @annual[year], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
 
     def annual_or_monthly_average(year)
-      return CpiPoint.new(value: @annual[year], granularity: :annual) if @annual.key?(year)
+      return CpiPoint.new(value: @annual[year], granularity: Granularity::ANNUAL) if @annual.key?(year)
 
       months = @monthly.select { |k, _| k.start_with?("#{year}-") }
       raise DataNotFound, missing_message(year) if months.empty?
 
-      CpiPoint.new(value: months.values.sum.to_f / months.size, granularity: :annual_from_monthly_avg)
+      avg = months.values.sum.to_f / months.size
+      CpiPoint.new(value: avg, granularity: Granularity::ANNUAL_FROM_MONTHLY_AVG)
     end
 
     def missing_message(key)

data/lib/timeprice/data_loader.rb

@@ -9,7 +9,7 @@ module Timeprice
   # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
   # {DataLoader.data_root=}.
   module DataLoader
-    SUPPORTED_SCHEMA_VERSION = 1
+    SUPPORTED_SCHEMA_VERSION = 2
 
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 

data/lib/timeprice/exchange.rb

@@ -4,10 +4,11 @@ require "date"
 require_relative "errors"
 require_relative "data_loader"
 require_relative "supported"
+require_relative "granularity"
 
 module Timeprice
   ExchangeResult = Data.define(
-    :amount, :original_amount, :from, :to, :date, :effective_date, :rate
+    :amount, :original_amount, :from, :to, :date, :effective_date, :rate, :granularity
   )
 
   # Historical FX conversion using bundled per-year USD-base rate files.
@@ -37,7 +38,7 @@ module Timeprice
 
       d = parse_date(date)
 
-      rate, eff_date = resolve_rate(from, to, d)
+      rate, eff_date, granularity = resolve_rate(from, to, d)
       ExchangeResult.new(
         amount: amount.to_f * rate,
         original_amount: amount.to_f,
@@ -45,40 +46,44 @@ module Timeprice
         to: to,
         date: d.to_s,
         effective_date: eff_date.to_s,
-        rate: rate
+        rate: rate,
+        granularity: granularity
       )
     end
 
-    # Returns [rate (Float), effective_date (Date)].
+    # Returns [rate (Float), effective_date (Date), granularity (Symbol)].
+    # Granularity is :daily when the rate came from a per-date entry, :annual
+    # when it came from the per-year `annual` fallback block. Triangulation
+    # merges both legs via Granularity.merge (worst-precision-wins).
     # Handles:
     #   - identity (from == to)
     #   - direct lookup of USD-base rate
     #   - inverse (foreign → USD)
     #   - triangulation through USD (both legs must resolve to SAME effective date)
     def resolve_rate(from, to, d)
-      return [1.0, d] if from == to
+      return [1.0, d, Granularity::DAILY] if from == to
 
       if from == BASE
-        rate, eff = lookup_usd_base(to, d)
-        [rate, eff]
+        lookup_usd_base(to, d)
       elsif to == BASE
-        rate, eff = lookup_usd_base(from, d)
-        [1.0 / rate, eff]
+        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 = lookup_usd_base(from, d)
-        usd_to_to,   eff_b = lookup_usd_base(to,   d)
+        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]
+        [usd_to_to / usd_to_from, eff_a, Granularity.merge(gran_a, gran_b)]
       end
     end
 
-    # Walk back up to MAX_FALLBACK_DAYS to find a rate.
-    # Returns [rate, effective_date].
+    # Walk back up to MAX_FALLBACK_DAYS to find a daily rate; if none, fall
+    # back to the year file's top-level `annual` block.
+    # Returns [rate, effective_date, granularity].
     def lookup_usd_base(currency, d)
       (0..MAX_FALLBACK_DAYS).each do |offset|
         candidate = d - offset
@@ -94,11 +99,23 @@ module Timeprice
         rate = rates_for_day[currency]
         next unless rate
 
-        return [rate.to_f, candidate]
+        return [rate.to_f, candidate, Granularity::DAILY]
       end
+
+      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}"
     end
 
+    # Consult the year file's top-level `annual` block. Returns Float or nil.
+    def annual_fallback(currency, year)
+      year_data = DataLoader.load_fx_year(year)
+      year_data.dig("annual", currency)&.to_f
+    rescue DataNotFound
+      nil
+    end
+
     def parse_date(date)
       case date
       when Date then date

data/lib/timeprice/granularity.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # Closed set of CPI-resolution granularities and the rules for combining /
+  # rendering them. Owns the lattice so callers don't hand-maintain it.
+  module Granularity
+    DAILY                        = :daily
+    MONTHLY                      = :monthly
+    ANNUAL                       = :annual
+    ANNUAL_FROM_MONTHLY_AVG      = :annual_from_monthly_avg
+    MONTHLY_FROM_ANNUAL_FALLBACK = :monthly_from_annual_fallback
+
+    # Most-degraded first — `merge` returns the first match.
+    # DAILY is the highest-precision FX tag; MONTHLY is the highest-precision
+    # CPI tag. Compare uses merge() across both legs, so the most-degraded
+    # tag in either leg wins.
+    PRECEDENCE = [
+      MONTHLY_FROM_ANNUAL_FALLBACK,
+      ANNUAL_FROM_MONTHLY_AVG,
+      ANNUAL,
+      MONTHLY,
+      DAILY,
+    ].freeze
+
+    HUMAN_LABELS = {
+      DAILY => "daily",
+      MONTHLY => "monthly",
+      ANNUAL => "annual",
+      ANNUAL_FROM_MONTHLY_AVG => "annual (avg of months)",
+      MONTHLY_FROM_ANNUAL_FALLBACK => "annual (month unavailable)",
+    }.freeze
+
+    module_function
+
+    # Worst-precision-wins merge across two or more endpoint granularities.
+    def merge(*tags)
+      PRECEDENCE.find { |t| tags.include?(t) } || MONTHLY
+    end
+
+    # Human-readable label for CLI output. Falls through to the symbol's
+    # string form so an unknown tag still renders something.
+    def humanize(tag)
+      HUMAN_LABELS.fetch(tag, tag.to_s)
+    end
+  end
+end

data/lib/timeprice/inflation.rb

@@ -3,15 +3,11 @@
 require_relative "errors"
 require_relative "data_loader"
 require_relative "cpi_lookup"
+require_relative "granularity"
 
 module Timeprice
-  # Value object returned by Inflation.adjust.
-  #
-  # granularity is one of:
-  #   :monthly                  — both ends resolved on monthly data
-  #   :annual                   — at least one end resolved on annual data
-  #   :annual_from_monthly_avg  — at least one end was an annual request resolved
-  #                               by averaging 12 months of monthly data
+  # Value object returned by Inflation.adjust. See {Granularity} for the set
+  # of possible `granularity` values and the worst-precision-wins merge rule.
   InflationResult = Data.define(
     :amount, :original_amount, :from, :to, :country,
     :from_index, :to_index, :granularity
@@ -54,7 +50,7 @@ module Timeprice
         country: country.to_s.upcase,
         from_index: from_point.value,
         to_index: to_point.value,
-        granularity: merge_granularity(from_point.granularity, to_point.granularity)
+        granularity: Granularity.merge(from_point.granularity, to_point.granularity)
       )
     end
 
@@ -68,14 +64,5 @@ module Timeprice
       result = adjust(amount: 1.0, from: from, to: to, country: country)
       result.amount - 1.0
     end
-
-    # If either end fell back to annual_from_monthly_avg, propagate that label;
-    # else if either is annual, propagate :annual; else :monthly.
-    def merge_granularity(a, b)
-      return :annual_from_monthly_avg if a == :annual_from_monthly_avg || b == :annual_from_monthly_avg
-      return :annual if a == :annual || b == :annual
-
-      :monthly
-    end
   end
 end

data/lib/timeprice/sources.rb

@@ -48,10 +48,10 @@ module Timeprice
         id: "vn_cpi",
         kind: "cpi",
         country: "VN",
-        name: "World Bank — FP.CPI.TOTL (annual)",
-        license: "CC BY 4.0",
-        license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "Source: World Bank, FP.CPI.TOTL",
+        name: "IMF Data Portal CPI dataflow (monthly primary) + World Bank FP.CPI.TOTL (annual fallback)",
+        license: "IMF: free reuse with attribution; World Bank: CC BY 4.0",
+        license_url: "https://www.imf.org/external/terms.htm",
+        attribution: "Sources: IMF Data Portal CPI dataflow; World Bank FP.CPI.TOTL",
       },
       {
         id: "fx_ecb",
@@ -66,7 +66,7 @@ module Timeprice
         id: "fx_vnd",
         kind: "fx",
         country: "VN",
-        name: "World Bank — PA.NUS.FCRF (VND annual average, broadcast daily)",
+        name: "World Bank — PA.NUS.FCRF (VND annual average, annual-granularity fallback)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
         attribution: "VND FX: World Bank, PA.NUS.FCRF",

data/lib/timeprice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Timeprice
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick
@@ -167,6 +167,7 @@ files:
 - lib/timeprice/data_loader.rb
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
+- lib/timeprice/granularity.rb
 - lib/timeprice/inflation.rb
 - lib/timeprice/point.rb
 - lib/timeprice/sources.rb