timeprice 0.4.0 → 0.6.0

data/data/manifest.json

@@ -0,0 +1,90 @@
+{
+  "countries": [
+    {
+      "code": "EU",
+      "cpi_file": "cpi/eu.json",
+      "currency": "EUR",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "JP",
+      "cpi_file": "cpi/jp.json",
+      "currency": "JPY",
+      "granularities": [
+        "annual"
+      ]
+    },
+    {
+      "code": "UK",
+      "cpi_file": "cpi/uk.json",
+      "currency": "GBP",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "US",
+      "cpi_file": "cpi/us.json",
+      "currency": "USD",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "VN",
+      "cpi_file": "cpi/vn.json",
+      "currency": "VND",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    }
+  ],
+  "fx": {
+    "annual_file": "fx/usd/_annual.json",
+    "base": "USD",
+    "currencies": [
+      "EUR",
+      "GBP",
+      "JPY",
+      "VND"
+    ],
+    "daily_years": [
+      1999,
+      2000,
+      2001,
+      2002,
+      2003,
+      2004,
+      2005,
+      2006,
+      2007,
+      2008,
+      2009,
+      2010,
+      2011,
+      2012,
+      2013,
+      2014,
+      2015,
+      2016,
+      2017,
+      2018,
+      2019,
+      2020,
+      2021,
+      2022,
+      2023,
+      2024,
+      2025,
+      2026
+    ]
+  },
+  "generated_at": "2026-05-11",
+  "schema_version": 4
+}

data/lib/timeprice/cli.rb

@@ -76,9 +76,9 @@ module Timeprice
     end
 
     desc "inflation AMOUNT", "Inflation-adjust an amount between two dates"
-    method_option :from,    type: :string, required: true, desc: "Source date (YYYY or YYYY-MM)"
-    method_option :to,      type: :string, required: true, desc: "Target date (YYYY or YYYY-MM)"
-    method_option :country, type: :string, required: true, desc: "Country code (US, UK, EU, JP, VN)"
+    method_option :from,    type: :string, required: true, desc: "Source date (YYYY, YYYY-MM, or YYYY-Qn)"
+    method_option :to,      type: :string, required: true, desc: "Target date (YYYY, YYYY-MM, or YYYY-Qn)"
+    method_option :country, type: :string, required: true, desc: "Country code (US, UK, EU, JP, VN, AU, CA, KR, CN, RU)"
     def inflation(amount)
       with_error_handling do
         result = Timeprice.inflation(

data/lib/timeprice/compare.rb

@@ -38,7 +38,7 @@ module Timeprice
     #   accepts a {Point} or a 2-tuple like `["USD", "2010"]` or `["USD", "2010-06"]`
     # @param to     [Timeprice::Point, Array(String, String)] destination point
     # @return [CompareResult]
-    # @raise [UnsupportedCurrency] if either currency is not in {Supported::CURRENCIES}
+    # @raise [UnsupportedCurrency] if either currency is not in {Supported.currencies}
     def run(amount:, from:, to:)
       from_point, to_point, to_country = resolve_points(from, to)
 

data/lib/timeprice/cpi_lookup.rb

@@ -8,54 +8,100 @@ module Timeprice
   # 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
-  # country's parsed CPI data hash. Knowing the JSON shape ("monthly" /
-  # "annual" string keys) is isolated here — Inflation just asks for points.
+  # Resolves CPI keys ("YYYY", "YYYY-MM", or "YYYY-Qn") to a CpiPoint against
+  # a single country's parsed CPI data hash. Knowing the JSON shape ("monthly"
+  # / "quarterly" / "annual" string keys) is isolated here — Inflation just
+  # asks for points.
   class CpiLookup
+    QUARTER_RE = /\A(\d{4})-Q([1-4])\z/
+
     def initialize(data)
       @data = data
-      @monthly = data["monthly"] || {}
-      @annual  = data["annual"]  || {}
+      @monthly   = data.dig("series", "monthly")   || {}
+      @quarterly = data.dig("series", "quarterly") || {}
+      @annual    = data.dig("series", "annual")    || {}
     end
 
-    # @param key [String] "YYYY" or "YYYY-MM"
+    # @param key [String] "YYYY", "YYYY-MM", or "YYYY-Qn"
     # @return [CpiPoint]
     # @raise [DataNotFound] if no CPI value covers `key`
     # @raise [ArgumentError] on malformed `key`
     def at(key)
       key = key.to_s
       case key
-      when /\A\d{4}-\d{2}\z/ then monthly_or_annual_fallback(key)
-      when /\A\d{4}\z/       then annual_or_monthly_average(key)
-      else raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
+      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)"
       end
     end
 
     private
 
-    def monthly_or_annual_fallback(month_key)
+    def monthly_or_fallbacks(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)
+      year, month = month_key.split("-").map(&:to_i)
+      qkey = format("%04d-Q%d", year, ((month - 1) / 3) + 1)
+      if @quarterly.key?(qkey)
+        return CpiPoint.new(value: @quarterly[qkey], granularity: Granularity::MONTHLY_FROM_QUARTERLY_FALLBACK)
+      end
+
+      year_key = month_key[0, 4]
+      raise DataNotFound, missing_message(month_key) unless @annual.key?(year_key)
 
-      CpiPoint.new(value: @annual[year], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
+      CpiPoint.new(value: @annual[year_key], granularity: Granularity::MONTHLY_FROM_ANNUAL_FALLBACK)
     end
 
-    def annual_or_monthly_average(year)
+    def quarterly_or_fallbacks(quarter_key)
+      if @quarterly.key?(quarter_key)
+        return CpiPoint.new(value: @quarterly[quarter_key],
+                            granularity: Granularity::QUARTERLY)
+      end
+
+      year_int, q = quarter_key.match(QUARTER_RE).captures.map(&:to_i)
+      first_month = ((q - 1) * 3) + 1
+      last_month  = q * 3
+      months = (first_month..last_month).map { |m| format("%04d-%02d", year_int, m) }
+                                        .map { |k| @monthly[k] }
+                                        .compact
+      if months.size == 3
+        return CpiPoint.new(value: months.sum.to_f / 3,
+                            granularity: Granularity::QUARTERLY_FROM_MONTHLY_AVG)
+      end
+
+      year = quarter_key[0, 4]
+      raise DataNotFound, missing_message(quarter_key) unless @annual.key?(year)
+
+      CpiPoint.new(value: @annual[year], granularity: Granularity::QUARTERLY_FROM_ANNUAL_FALLBACK)
+    end
+
+    def annual_or_derived(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?
+      months   = @monthly.select { |k, _| k.start_with?("#{year}-") }
+      quarters = @quarterly.select { |k, _| k.start_with?("#{year}-Q") }
+
+      # Prefer complete-period averages over partials, and within each, prefer
+      # monthly resolution. Partial tags distinguish biased estimates (e.g.
+      # only Jan-Feb populated) from a true full-year mean.
+      return average(months, 12, Granularity::ANNUAL_FROM_MONTHLY_AVG) if months.size == 12
+      return average(quarters, 4, Granularity::ANNUAL_FROM_QUARTERLY_AVG) if quarters.size == 4
+      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)
+    end
 
-      avg = months.values.sum.to_f / months.size
-      CpiPoint.new(value: avg, granularity: Granularity::ANNUAL_FROM_MONTHLY_AVG)
+    def average(series, divisor, granularity)
+      CpiPoint.new(value: series.values.sum.to_f / divisor, granularity: granularity)
     end
 
     def missing_message(key)
       country = @data["country"]
       ranges = []
       ranges << "monthly #{@monthly.keys.min}..#{@monthly.keys.max}" if @monthly.any?
+      ranges << "quarterly #{@quarterly.keys.min}..#{@quarterly.keys.max}" if @quarterly.any?
       ranges << "annual #{@annual.keys.min}..#{@annual.keys.max}" if @annual.any?
       hint = ranges.empty? ? "" : " (supported: #{ranges.join(", ")})"
       "No CPI data for #{key.inspect} in #{country}#{hint}"

data/lib/timeprice/data_loader.rb

@@ -2,19 +2,22 @@
 
 require "json"
 require_relative "errors"
-require_relative "supported"
 
 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 = 2
+    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
-      # @return [String] absolute path to the directory containing `cpi/` and `fx/`
+      # @return [String] absolute path to the directory containing `cpi/`, `fx/`, `manifest.json`.
       def data_root
         ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
       end
@@ -32,19 +35,36 @@ module Timeprice
       def clear_cache!
         @cpi_cache = {}
         @fx_cache = {}
+        @manifest_cache = {}
+        @annual_fallback_cache = {}
+      end
+
+      # Load the top-level manifest describing the bundled dataset.
+      # @return [Hash]
+      # @raise [DataNotFound] if `manifest.json` is missing
+      def load_manifest
+        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."
+          end
+
+          parse_with_schema(path)
+        end
       end
 
       # Load the CPI series for a supported country.
       # @param country [String]
-      # @return [Hash] parsed JSON with "monthly" / "annual" / metadata keys
-      # @raise [UnsupportedCountry] if `country` is not in {Supported::COUNTRIES}
+      # @return [Hash] parsed JSON with "series" / "index" / "provenance" / "providers"
+      # @raise [UnsupportedCountry] if `country` is not in {Supported.countries}
       # @raise [DataNotFound]       if the file is missing
       # @raise [UnsupportedSchemaVersion] if the file uses a future schema
       def load_cpi(country)
         key = country.to_s.downcase
         code = country.to_s.upcase
         cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless Supported::COUNTRIES.include?(code)
+          raise UnsupportedCountry, code unless Supported.country?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
@@ -58,7 +78,7 @@ module Timeprice
 
       # Load the FX rates for a year.
       # @param year [Integer, String]
-      # @return [Hash] parsed JSON with a "rates" map of date → currency → Float
+      # @return [Hash] parsed JSON with `rates` (and optional `annual`) blocks
       # @raise [DataNotFound] if the per-year file is missing
       def load_fx_year(year)
         key = year.to_i
@@ -70,6 +90,17 @@ module Timeprice
         end
       end
 
+      # Load the sparse historical FX annual-only fallback file, if present.
+      # Returns nil when no fallback file ships with this data root.
+      # @return [Hash, nil]
+      def load_fx_annual_fallback
+        return @annual_fallback_cache[data_root] if @annual_fallback_cache&.key?(data_root)
+
+        @annual_fallback_cache ||= {}
+        path = File.join(data_root, "fx", "usd", "_annual.json")
+        @annual_fallback_cache[data_root] = File.exist?(path) ? parse_with_schema(path) : nil
+      end
+
       private
 
       def cpi_cache
@@ -80,13 +111,21 @@ module Timeprice
         @fx_cache ||= {}
       end
 
+      def manifest_cache
+        @manifest_cache ||= {}
+      end
+
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]
-        raise UnsupportedSchemaVersion.new(version, path) unless version == SUPPORTED_SCHEMA_VERSION
+        raise UnsupportedSchemaVersion.new(version, path) unless SUPPORTED_SCHEMA_VERSIONS.include?(version)
 
         data
       end
     end
   end
 end
+
+# Supported is loaded by the top-level entry point. Referenced lazily inside
+# load_cpi to avoid a require cycle (Supported reads the manifest via DataLoader).
+require_relative "supported" unless defined?(Timeprice::Supported)

data/lib/timeprice/errors.rb

@@ -7,23 +7,23 @@ module Timeprice
   # to handle anything the gem can throw at you.
   class Error < StandardError; end
 
-  # Raised when a country code is not in {Supported::COUNTRIES}.
+  # Raised when a country code is not in {Supported.countries}.
   class UnsupportedCountry < Error
     attr_reader :country
 
     def initialize(country)
       @country = country
-      super("Unsupported country: #{country.inspect} (supported: #{Supported::COUNTRIES.join(", ")})")
+      super("Unsupported country: #{country.inspect} (supported: #{Supported.countries.join(", ")})")
     end
   end
 
-  # Raised when a currency code is not in {Supported::CURRENCIES}.
+  # Raised when a currency code is not in {Supported.currencies}.
   class UnsupportedCurrency < Error
     attr_reader :currency
 
     def initialize(currency)
       @currency = currency
-      super("Unsupported currency: #{currency.inspect} (supported: #{Supported::CURRENCIES.join(", ")})")
+      super("Unsupported currency: #{currency.inspect} (supported: #{Supported.currencies.join(", ")})")
     end
   end
 

data/lib/timeprice/exchange.rb

@@ -33,8 +33,8 @@ module Timeprice
     def convert(amount:, from:, to:, date:)
       from = from.to_s.upcase
       to   = to.to_s.upcase
-      raise UnsupportedCurrency, from unless Supported::CURRENCIES.include?(from)
-      raise UnsupportedCurrency, to   unless Supported::CURRENCIES.include?(to)
+      raise UnsupportedCurrency, from unless Supported.currency?(from)
+      raise UnsupportedCurrency, to   unless Supported.currency?(to)
 
       d = parse_date(date)
 
@@ -82,7 +82,7 @@ module Timeprice
     end
 
     # 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.
+    # back to data/fx/usd/_annual.json (the single source of annual FX truth).
     # Returns [rate, effective_date, granularity].
     def lookup_usd_base(currency, d)
       (0..MAX_FALLBACK_DAYS).each do |offset|
@@ -108,12 +108,12 @@ module Timeprice
       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.
+    # Consult data/fx/usd/_annual.json. 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
+      fallback = DataLoader.load_fx_annual_fallback
+      return nil unless fallback
+
+      fallback.dig("annual", year.to_s, currency)&.to_f
     end
 
     def parse_date(date)

data/lib/timeprice/granularity.rb

@@ -4,20 +4,44 @@ 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
+    DAILY                          = :daily
+    MONTHLY                        = :monthly
+    QUARTERLY                      = :quarterly
+    ANNUAL                         = :annual
+    ANNUAL_FROM_MONTHLY_AVG         = :annual_from_monthly_avg
+    ANNUAL_FROM_QUARTERLY_AVG       = :annual_from_quarterly_avg
+    ANNUAL_FROM_PARTIAL_MONTHS      = :annual_from_partial_months
+    ANNUAL_FROM_PARTIAL_QUARTERS    = :annual_from_partial_quarters
+    QUARTERLY_FROM_ANNUAL_FALLBACK  = :quarterly_from_annual_fallback
+    QUARTERLY_FROM_MONTHLY_AVG      = :quarterly_from_monthly_avg
+    MONTHLY_FROM_QUARTERLY_FALLBACK = :monthly_from_quarterly_fallback
+    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.
+    # 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.
+    #
+    # Ordering rationale (worst → best):
+    #   1. Cross-grain fallbacks where the asked resolution is finer than
+    #      what's available (annual stretched to month/quarter).
+    #   2. Partial-period averages — asked annual but only some months/
+    #      quarters in the year are populated. Highly biased by seasonality.
+    #   3. Same-or-coarser fallback (quarter stretched to month).
+    #   4. Full-period derived averages (complete 4-quarter or 12-month mean
+    #      standing in for the asked coarser resolution).
+    #   5. Native series at the asked resolution.
     PRECEDENCE = [
       MONTHLY_FROM_ANNUAL_FALLBACK,
+      ANNUAL_FROM_PARTIAL_QUARTERS,
+      ANNUAL_FROM_PARTIAL_MONTHS,
+      QUARTERLY_FROM_ANNUAL_FALLBACK,
+      MONTHLY_FROM_QUARTERLY_FALLBACK,
+      ANNUAL_FROM_QUARTERLY_AVG,
+      QUARTERLY_FROM_MONTHLY_AVG,
       ANNUAL_FROM_MONTHLY_AVG,
       ANNUAL,
+      QUARTERLY,
       MONTHLY,
       DAILY,
     ].freeze
@@ -25,9 +49,16 @@ module Timeprice
     HUMAN_LABELS = {
       DAILY => "daily",
       MONTHLY => "monthly",
+      QUARTERLY => "quarterly",
       ANNUAL => "annual",
       ANNUAL_FROM_MONTHLY_AVG => "annual (avg of months)",
-      MONTHLY_FROM_ANNUAL_FALLBACK => "annual (month unavailable)",
+      ANNUAL_FROM_QUARTERLY_AVG => "annual (avg of quarters)",
+      ANNUAL_FROM_PARTIAL_MONTHS => "annual (partial-year, avg of available months)",
+      ANNUAL_FROM_PARTIAL_QUARTERS => "annual (partial-year, avg of available quarters)",
+      QUARTERLY_FROM_ANNUAL_FALLBACK => "quarter (annual fallback)",
+      QUARTERLY_FROM_MONTHLY_AVG => "quarter (avg of months)",
+      MONTHLY_FROM_QUARTERLY_FALLBACK => "month (quarter unavailable)",
+      MONTHLY_FROM_ANNUAL_FALLBACK => "month (annual fallback)",
     }.freeze
 
     module_function

data/lib/timeprice/inflation.rb

@@ -21,18 +21,18 @@ module Timeprice
     end
   end
 
-  # CPI-based inflation adjustment for the {Supported::COUNTRIES} list.
+  # CPI-based inflation adjustment for the {Supported.countries} list.
   module Inflation
     module_function
 
     # Adjust `amount` from date `from` to date `to` using country CPI.
     #
-    # Dates accept "YYYY" or "YYYY-MM".
+    # Dates accept "YYYY", "YYYY-MM", or "YYYY-Qn" (Q1..Q4).
     #
     # @param amount  [Numeric]
-    # @param from    [String] source date ("YYYY" or "YYYY-MM")
-    # @param to      [String] target date ("YYYY" or "YYYY-MM")
-    # @param country [String] country code (see {Supported::COUNTRIES})
+    # @param from    [String] source date ("YYYY", "YYYY-MM", or "YYYY-Qn")
+    # @param to      [String] target date ("YYYY", "YYYY-MM", or "YYYY-Qn")
+    # @param country [String] country code (see {Supported.countries})
     # @return [InflationResult]
     # @raise [UnsupportedCountry] if `country` is not supported
     # @raise [DataNotFound]       if no CPI data covers the requested period

data/lib/timeprice/sources/coverage.rb

@@ -5,9 +5,10 @@ require_relative "../data_loader"
 
 module Timeprice
   module Sources
-    # Computes coverage strings for bundled data sources at runtime. All
-    # filesystem reads happen here so the Sources attribution registry stays
-    # a pure data table.
+    # Computes coverage strings for bundled data sources at runtime by reading
+    # the structured `provenance` blocks in v3 data files. The Sources
+    # attribution registry stays a pure data table; Coverage is the only
+    # place that touches the filesystem.
     module Coverage
       module_function
 
@@ -25,46 +26,40 @@ module Timeprice
 
       def cpi(country)
         data = DataLoader.load_cpi(country)
-        monthly = (data["monthly"] || {}).keys.sort
-        annual  = (data["annual"]  || {}).keys.sort
+        monthly = data.dig("series", "monthly") || {}
+        annual  = data.dig("series", "annual") || {}
         parts = []
-        parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
-        parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
+        parts << "monthly #{monthly.keys.min}..#{monthly.keys.max} (#{monthly.size})" if monthly.any?
+        parts << "annual #{annual.keys.min}..#{annual.keys.max} (#{annual.size})" if annual.any?
         parts.join(", ")
       end
 
       def fx(id)
-        years = fx_years
-        return "no data" if years.empty?
-
-        id == "fx_vnd" ? vnd_summary(years) : ecb_summary(years)
-      end
-
-      def fx_years
-        Dir[File.join(fx_root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
-      end
-
-      def vnd_summary(years)
-        with_vnd = years.select { |y| year_has_currency?(y, %w[VND]) }
-        return "no VND data" if with_vnd.empty?
-
-        "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
+        case id
+        when "fx_ecb" then ecb_summary
+        when "fx_vnd" then vnd_summary
+        else "n/a"
+        end
       end
 
-      def ecb_summary(years)
-        ecb_years = years.select { |y| year_has_currency?(y, %w[EUR GBP JPY]) }
-        return "no ECB data" if ecb_years.empty?
+      # Frankfurter (ECB) → daily EUR/GBP/JPY in per-year files. Range derived
+      # from the manifest's `daily_years` list.
+      def ecb_summary
+        years = DataLoader.load_manifest.dig("fx", "daily_years") || []
+        return "no ECB data" if years.empty?
 
-        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
+        "USD↔EUR/GBP/JPY daily #{years.first}..#{years.last}"
       end
 
-      def year_has_currency?(year, codes)
-        rates = JSON.parse(File.read(File.join(fx_root, "#{year}.json")))["rates"]
-        rates.any? { |_, v| v.keys.intersect?(codes) }
-      end
+      # All annual FX (today only VND) lives in data/fx/usd/_annual.json.
+      def vnd_summary
+        fallback = DataLoader.load_fx_annual_fallback
+        years = (fallback&.dig("annual") || {})
+                .select { |_y, ccy_hash| ccy_hash.key?("VND") }
+                .keys.map(&:to_i).sort
+        return "no VND data" if years.empty?
 
-      def fx_root
-        File.join(DataLoader.data_root, "fx", "usd")
+        "USD↔VND #{years.first}..#{years.last}"
       end
     end
   end