timeprice 0.6.0 → 0.8.0

data/lib/timeprice/forecast/cagr.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Timeprice
+  module Forecast
+    # Pure math: trailing CAGR and σ of year-over-year changes.
+    #
+    # The series is a hash mapping date strings (`"YYYY"` or `"YYYY-MM"`) to
+    # numeric values. The trailing window is anchored on `last_date` and
+    # extends `window_years` backward. CAGR is the annualized geometric
+    # return between the first and last samples in the window. Sigma is the
+    # sample stdev of 1-year-spaced returns within the window.
+    #
+    # No I/O, no DataLoader. Pure function — call from anywhere.
+    #
+    # @api private
+    module Cagr
+      module_function
+
+      # @param series       [Hash{String => Numeric}]
+      # @param last_date    [String] anchor ("YYYY" or "YYYY-MM")
+      # @param window_years [Integer]
+      # @return [Hash] { cagr: Float, sigma_yoy: Float, window_start: String,
+      #                  window_end: String, samples: Integer }
+      def compute(series:, last_date:, window_years:)
+        end_date   = parse(last_date)
+        start_date = shift_years(end_date, -window_years)
+
+        sorted = series
+                 .select { |k, _| within?(k, start_date, end_date) }
+                 .sort_by { |k, _| parse(k) }
+
+        fail ArgumentError, "need at least 2 points in window" if sorted.size < 2
+
+        cagr = annualised_return(sorted)
+
+        {
+          cagr: cagr,
+          sigma_yoy: stdev_of_yoy(sorted),
+          window_start: sorted.first.first,
+          window_end: sorted.last.first,
+          samples: sorted.size,
+        }
+      end
+
+      def annualised_return(sorted)
+        first_v = sorted.first.last.to_f
+        last_v  = sorted.last.last.to_f
+
+        fail ArgumentError, "first window value must be positive (got #{first_v})" unless first_v.positive?
+        fail ArgumentError, "last window value must be positive (got #{last_v})"   unless last_v.positive?
+
+        years_elapsed = (parse(sorted.last.first) - parse(sorted.first.first)) / 365.2425
+        fail ArgumentError, "window has zero elapsed time" unless years_elapsed.positive?
+
+        ((last_v / first_v)**(1.0 / years_elapsed)) - 1.0
+      end
+
+      def parse(s)
+        s = s.to_s
+        return ::Date.new(s.to_i, 1, 1) if s.length == 4
+
+        y, m = s.split("-").map(&:to_i)
+        ::Date.new(y, m, 1)
+      end
+
+      def shift_years(date, years)
+        ::Date.new(date.year + years, date.month, 1)
+      end
+
+      def within?(key, start_date, end_date)
+        d = parse(key)
+        d.between?(start_date, end_date)
+      end
+
+      # Stdev of simple (arithmetic) 1-year-spaced returns within the window.
+      # Returns 0.0 when fewer than 2 paired samples exist.
+      def stdev_of_yoy(sorted)
+        by_date = sorted.to_h
+        returns = sorted.filter_map do |key, value|
+          prior_key = shift_years(parse(key), -1).strftime(key.length == 4 ? "%Y" : "%Y-%m")
+          prior = by_date[prior_key]
+          next unless prior&.positive?
+
+          (value.to_f / prior) - 1.0
+        end
+        return 0.0 if returns.size < 2
+
+        mean = returns.sum / returns.size
+        variance = returns.sum { |r| (r - mean)**2 } / (returns.size - 1)
+        Math.sqrt(variance)
+      end
+    end
+  end
+end

data/lib/timeprice/forecast/cpi_forecaster.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../forecast"
+require_relative "../data_loader"
+require_relative "../errors"
+require_relative "cagr"
+
+module Timeprice
+  module Forecast
+    # Project a country's CPI index forward from the last bundled data point.
+    #
+    # @api private
+    module CpiForecaster
+      module_function
+
+      DEFAULT_WINDOW_YEARS = 10
+      HORIZON_CAP_YEARS    = 5
+
+      # @param country      [String]
+      # @param target       [String] "YYYY" or "YYYY-MM"
+      # @param window_years [Integer]
+      # @return [Forecast::Result]
+      # @raise [DataNotFound] if the CPI series has no usable monthly or annual data
+      def project(country:, target:, window_years: DEFAULT_WINDOW_YEARS)
+        series = load_series(country)
+        last_key, last_value = last_entry(series)
+        horizon_months = months_between(last_key, target)
+        warnings = build_warnings(series, last_key, window_years, horizon_months)
+        stats = Cagr.compute(series: series, last_date: last_key, window_years: window_years)
+        build_result(last_key: last_key, last_value: last_value, target: target,
+                     horizon_months: horizon_months, window_years: window_years,
+                     stats: stats, warnings: warnings)
+      end
+
+      # Prefer monthly when present; fall back to annual.
+      def pick_series(data)
+        monthly = data.dig("series", "monthly") || {}
+        return monthly unless monthly.empty?
+
+        data.dig("series", "annual") || {}
+      end
+
+      def months_between(from_key, to_key)
+        f = Cagr.parse(from_key)
+        t = Cagr.parse(to_key)
+        ((t.year - f.year) * 12) + (t.month - f.month)
+      end
+
+      def load_series(country)
+        data = DataLoader.load_cpi(country.to_s.upcase)
+        series = pick_series(data)
+        fail DataNotFound, "no CPI series for #{country}" if series.empty?
+
+        series
+      end
+
+      def last_entry(series)
+        last_key = series.keys.max_by { |k| Cagr.parse(k) }
+        [last_key, series[last_key].to_f]
+      end
+
+      def build_warnings(series, last_key, window_years, horizon_months)
+        warnings = []
+        earliest = series.keys.map { |k| Cagr.parse(k).year }.min
+        warnings << "insufficient_window" if Cagr.parse(last_key).year - window_years < earliest
+        warnings << "horizon_exceeds_cap" if horizon_months > HORIZON_CAP_YEARS * 12
+        warnings.uniq
+      end
+
+      def build_result(last_key:, last_value:, target:, horizon_months:, window_years:, stats:, warnings:)
+        years_forward = horizon_months / 12.0
+        value = last_value * ((1.0 + stats[:cagr])**years_forward)
+        low   = last_value * ((1.0 + stats[:cagr] - stats[:sigma_yoy])**years_forward)
+        high  = last_value * ((1.0 + stats[:cagr] + stats[:sigma_yoy])**years_forward)
+
+        Forecast::Result.new(
+          value: value, low: low, high: high,
+          projection_method: "cagr_trailing",
+          window_years: window_years,
+          sigma_pct: stats[:sigma_yoy],
+          last_known_date: last_key,
+          target_date: target,
+          horizon_months: horizon_months,
+          basis_kind: :cpi,
+          warnings: warnings.uniq
+        )
+      end
+    end
+  end
+end

data/lib/timeprice/forecast/fx_forecaster.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "../forecast"
+require_relative "../data_loader"
+require_relative "../errors"
+require_relative "cagr"
+
+module Timeprice
+  module Forecast
+    # Project a currency-pair FX rate forward using the same trailing-CAGR
+    # mechanism as CpiForecaster, but with FX-appropriate defaults: 5-year
+    # window, 2-year horizon cap.
+    #
+    # The annual series is reconstructed by reading each bundled year file
+    # and pulling the year-end (or annual-average where present) rate. The
+    # daily granularity that {Exchange} works with is too noisy to anchor a
+    # multi-year extrapolation — annualizing first is the whole point.
+    #
+    # @api private
+    module FxForecaster
+      module_function
+
+      DEFAULT_WINDOW_YEARS = 5
+      HORIZON_CAP_YEARS    = 2
+
+      def project(from:, to:, target:, window_years: DEFAULT_WINDOW_YEARS)
+        from = from.to_s.upcase
+        to   = to.to_s.upcase
+
+        series = load_annual_series(from, to)
+        fail DataNotFound, "no FX series for #{from}->#{to}" if series.empty?
+
+        last_key       = series.keys.max_by { |k| Cagr.parse(k) }
+        last_value     = series[last_key].to_f
+        horizon_months = months_between(last_key, target)
+        earliest_year  = series.keys.map { |k| Cagr.parse(k).year }.min
+        warnings       = []
+        warnings << "insufficient_window" if Cagr.parse(last_key).year - window_years < earliest_year
+        warnings << "horizon_exceeds_cap" if horizon_months > HORIZON_CAP_YEARS * 12
+
+        stats = Cagr.compute(series: series, last_date: last_key, window_years: window_years)
+
+        build_result(
+          last_key: last_key, last_value: last_value,
+          target: target, horizon_months: horizon_months,
+          window_years: window_years, stats: stats, warnings: warnings
+        )
+      end
+
+      # Build an annual {year_string => rate} series by reading each FX year
+      # file and computing a daily average for the requested currency pair.
+      # Falls back to the _annual.json file for years where the daily file
+      # does not cover the requested pair. Returns {} if no data is found.
+      def load_annual_series(from, to)
+        root = File.join(DataLoader.data_root, "fx", "usd")
+        return {} unless File.directory?(root)
+
+        fallback = DataLoader.load_fx_annual_fallback
+        years = Dir.children(root).filter_map do |f|
+          Regexp.last_match(1).to_i if f =~ /\A(\d{4})\.json\z/
+        end.sort
+
+        years.each_with_object({}) do |year, acc|
+          rate = pick_year_rate(DataLoader.load_fx_year(year), from, to)
+          rate ||= pick_annual_fallback_rate(fallback, year, from, to) if fallback
+          acc[year.to_s] = rate if rate
+        end
+      end
+
+      # Compute an annual average rate for +from+->+to+ from a year-file
+      # payload. Year-file rates are stored as USD->currency daily rates.
+      #
+      #   from == "USD"  => average rates[date][to] across all dates
+      #   to   == "USD"  => average rates[date][from], then invert
+      #   else (cross)   => per-date to/from ratio, then average
+      def pick_year_rate(payload, from, to)
+        daily = payload["rates"]
+        return nil unless daily.is_a?(Hash) && !daily.empty?
+
+        if from == "USD"
+          daily_avg(daily.values, to)
+        elsif to == "USD"
+          invert_avg(daily.values, from)
+        else
+          cross_avg(daily.values, from, to)
+        end
+      end
+
+      # Extract an annual rate for +from+->+to+ from the _annual.json fallback.
+      # Fallback stores USD->currency annual averages keyed by year string.
+      def pick_annual_fallback_rate(fallback, year, from, to)
+        ann = fallback.dig("annual", year.to_s)
+        return nil unless ann.is_a?(Hash)
+
+        if from == "USD"
+          ann[to]&.to_f
+        elsif to == "USD"
+          invert_scalar(ann[from]&.to_f)
+        else
+          cross_scalar(ann[from]&.to_f, ann[to]&.to_f)
+        end
+      end
+
+      def months_between(from_key, to_key)
+        f = Cagr.parse(from_key)
+        t = Cagr.parse(to_key)
+        ((t.year - f.year) * 12) + (t.month - f.month)
+      end
+
+      def build_result(last_key:, last_value:, target:, horizon_months:, window_years:, stats:, warnings:)
+        years_forward = horizon_months / 12.0
+        value = last_value * ((1.0 + stats[:cagr])**years_forward)
+        low   = last_value * ((1.0 + stats[:cagr] - stats[:sigma_yoy])**years_forward)
+        high  = last_value * ((1.0 + stats[:cagr] + stats[:sigma_yoy])**years_forward)
+
+        Forecast::Result.new(
+          value: value, low: low, high: high,
+          projection_method: "cagr_trailing",
+          window_years: window_years,
+          sigma_pct: stats[:sigma_yoy],
+          last_known_date: last_key,
+          target_date: target,
+          horizon_months: horizon_months,
+          basis_kind: :fx,
+          warnings: warnings.uniq
+        )
+      end
+
+      # --- private helpers ---
+
+      # Average USD->+currency+ values across all day_rates hashes.
+      def daily_avg(day_rates_list, currency)
+        vals = day_rates_list.filter_map { |dr| dr[currency]&.to_f }
+        return nil if vals.empty?
+
+        vals.sum / vals.size
+      end
+
+      # Average USD->+currency+ then invert to get currency->USD.
+      def invert_avg(day_rates_list, currency)
+        mean = daily_avg(day_rates_list, currency)
+        invert_scalar(mean)
+      end
+
+      # Average the per-day cross rate (USD->to / USD->from) for dates where
+      # both currencies are present.
+      def cross_avg(day_rates_list, from, to)
+        pairs = day_rates_list.filter_map do |dr|
+          usd_from = dr[from]&.to_f
+          usd_to   = dr[to]&.to_f
+          cross_scalar(usd_from, usd_to)
+        end
+        return nil if pairs.empty?
+
+        pairs.sum / pairs.size
+      end
+
+      # Invert a single USD->X scalar to X->USD; nil if zero or nil.
+      def invert_scalar(val)
+        return nil unless val&.positive?
+
+        1.0 / val
+      end
+
+      # Compute cross rate from two USD->X scalars; nil if either is nil/zero.
+      def cross_scalar(usd_from, usd_to)
+        return nil unless usd_from&.positive? && usd_to
+
+        usd_to / usd_from
+      end
+    end
+  end
+end

data/lib/timeprice/forecast.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # Forward-projection of CPI / FX series past the last bundled data point.
+  #
+  # Method: trailing-window CAGR for the point estimate, ±1σ of trailing
+  # year-over-year changes for the band. Pure-Ruby, deterministic, no
+  # network calls or stats dependencies.
+  #
+  # All results are explicitly tagged so callers never confuse them with
+  # measured data. The {Forecast::Result#warnings} array surfaces horizon-cap
+  # violations and insufficient-window conditions.
+  module Forecast
+    Result = Data.define(
+      :value, :low, :high,
+      :projection_method, :window_years, :sigma_pct,
+      :last_known_date, :target_date, :horizon_months,
+      :basis_kind, :warnings
+    )
+  end
+end

data/lib/timeprice/inflation.rb

@@ -4,6 +4,7 @@ require_relative "errors"
 require_relative "data_loader"
 require_relative "cpi_lookup"
 require_relative "granularity"
+require_relative "date"
 
 module Timeprice
   # Value object returned by Inflation.adjust. See {Granularity} for the set
@@ -22,6 +23,11 @@ module Timeprice
   end
 
   # CPI-based inflation adjustment for the {Supported.countries} list.
+  #
+  # @api private
+  # The supported public entry point is {Timeprice.inflation}. Direct
+  # references to this module will move to `Timeprice::Internal::Inflation`
+  # in a future release.
   module Inflation
     module_function
 
@@ -37,16 +43,18 @@ module Timeprice
     # @raise [UnsupportedCountry] if `country` is not supported
     # @raise [DataNotFound]       if no CPI data covers the requested period
     def adjust(amount:, from:, to:, country:)
+      from = Timeprice::Date.coerce(from)
+      to   = Timeprice::Date.coerce(to)
       lookup = CpiLookup.new(DataLoader.load_cpi(country))
-      from_point = lookup.at(from)
-      to_point   = lookup.at(to)
+      from_point = lookup.at(from.to_s)
+      to_point   = lookup.at(to.to_s)
 
       ratio = to_point.value.to_f / from_point.value
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
-        from: from,
-        to: to,
+        from: from.to_s,
+        to: to.to_s,
         country: country.to_s.upcase,
         from_index: from_point.value,
         to_index: to_point.value,

data/lib/timeprice/metadata.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "data_loader"
+require_relative "supported"
+require_relative "version"
+require_relative "metadata_snapshot"
+
+module Timeprice
+  # Describes the bundled dataset so external surfaces (the website, other
+  # tools) can render dropdowns, date pickers, and version pills without
+  # hardcoding country lists, currency lists, or date ranges.
+  #
+  # See {Timeprice.metadata} for the public entry point.
+  #
+  # @api private
+  # Direct references will move to `Timeprice::Internal::Metadata` in a
+  # future release.
+  module Metadata
+    # ISO 3166-style display names for the countries shipped today.
+    COUNTRY_NAMES = {
+      "AU" => "Australia",
+      "CA" => "Canada",
+      "CN" => "China",
+      "EU" => "Eurozone",
+      "JP" => "Japan",
+      "KR" => "South Korea",
+      "RU" => "Russia",
+      "UK" => "United Kingdom",
+      "US" => "United States",
+      "VN" => "Vietnam",
+    }.freeze
+
+    # ISO 4217 display names for the currencies shipped today.
+    CURRENCY_NAMES = {
+      "AUD" => "Australian dollar",
+      "CAD" => "Canadian dollar",
+      "CNY" => "Chinese yuan",
+      "EUR" => "Euro",
+      "GBP" => "British pound",
+      "JPY" => "Japanese yen",
+      "KRW" => "South Korean won",
+      "RUB" => "Russian ruble",
+      "USD" => "US dollar",
+      "VND" => "Vietnamese dong",
+    }.freeze
+
+    module_function
+
+    # Build the metadata snapshot.
+    # @return [MetadataSnapshot]
+    def build
+      manifest = DataLoader.load_manifest
+      countries = (manifest["countries"] || []).map { |c| country_entry(c) }
+      currencies = Supported.currencies.map { |code| { code: code, name: CURRENCY_NAMES[code] || code } }
+      MetadataSnapshot.new(
+        version: VERSION,
+        generated_at: manifest["generated_at"],
+        countries: deep_freeze(countries),
+        currencies: deep_freeze(currencies),
+        fx: deep_freeze(fx_entry(manifest))
+      )
+    end
+
+    # Range info comes from the manifest (`cpi_ranges`), pre-computed at
+    # manifest generation time. Falls back to walking the CPI file for any
+    # country missing the field — older manifests, or local data roots
+    # produced by hand.
+    def country_entry(country)
+      code = country["code"]
+      ranges = country["cpi_ranges"] || derive_cpi_ranges(code)
+      per_granularity = ranges.each_with_object({}) do |(gran, range), acc|
+        acc[gran.to_sym] = { min: range["min"], max: range["max"] }
+      end
+      {
+        code: code,
+        name: COUNTRY_NAMES[code] || code,
+        currency: country["currency"],
+        granularities: country["granularities"] || per_granularity.keys.map(&:to_s),
+        cpi: per_granularity,
+      }
+    end
+
+    def derive_cpi_ranges(code)
+      cpi = DataLoader.load_cpi(code)
+      series = cpi["series"] || {}
+      series.each_with_object({}) do |(granularity, points), acc|
+        next unless points.is_a?(Hash) && !points.empty?
+
+        keys = points.keys.sort
+        acc[granularity] = { "min" => keys.first, "max" => keys.last }
+      end
+    end
+
+    # Bounds come from the manifest (`fx.daily_min`/`fx.daily_max`). Older
+    # manifests without those keys: peek at the earliest/latest year files.
+    def fx_entry(manifest)
+      fx = manifest["fx"] || {}
+      base = fx["base"]
+      years = fx["daily_years"] || []
+      return { base: base, daily_min: nil, daily_max: nil } if years.empty?
+
+      daily_min = fx["daily_min"]
+      daily_max = fx["daily_max"]
+      if daily_min.nil? || daily_max.nil?
+        first = DataLoader.load_fx_year(years.min)
+        last  = DataLoader.load_fx_year(years.max)
+        daily_min ||= (first["rates"] || {}).keys.min
+        daily_max ||= (last["rates"] || {}).keys.max
+      end
+      { base: base, daily_min: daily_min, daily_max: daily_max }
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash  then value.each_value { |v| deep_freeze(v) }.freeze
+      when Array then value.each { |v| deep_freeze(v) }.freeze
+      else value.frozen? ? value : value.freeze
+      end
+    end
+  end
+end

data/lib/timeprice/metadata_snapshot.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Timeprice
+  # Frozen value object describing the bundled dataset: version, refresh
+  # date, country list with CPI ranges, currency list with display names,
+  # and FX coverage. Replaces the previous Hash return shape on
+  # {Timeprice.metadata}.
+  #
+  # `[]`, `to_h`, and `to_json` are kept compatible with the old Hash
+  # interface so downstream consumers (the website, this gem's specs)
+  # don't need a coordinated rewrite.
+  MetadataSnapshot = Data.define(:version, :generated_at, :countries, :currencies, :fx) do
+    def [](key)
+      to_h[key]
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/timeprice/point.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "date"
+
 module Timeprice
   # A (currency, date) pair used as input to {Timeprice.compare}.
   #
@@ -13,6 +15,12 @@ module Timeprice
   #   Timeprice::Point.coerce(["USD", "2010"])
   #   Timeprice::Point.coerce(["2010", "USD"])
   Point = Data.define(:currency, :date) do
+    # Canonical constructor. Accepts a stdlib-string or Timeprice::Date
+    # for the date argument; stores the canonical string form.
+    def self.parse(currency, date)
+      new(currency: currency.to_s.upcase, date: Timeprice::Date.coerce(date).to_s)
+    end
+
     # Coerce input into a Point. Accepts:
     #   - {Point} (returned as-is)
     #   - 2-element Array of [currency, date] in either order
@@ -28,11 +36,11 @@ module Timeprice
         a, b = input.map(&:to_s)
         currency = [a, b].find { |s| s.match?(/\A[A-Za-z]{3}\z/) }
         date     = [a, b].find { |s| s.match?(/\A\d{4}(-\d{2}(-\d{2})?)?\z/) }
-        raise ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
+        fail ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
 
         new(currency: currency.upcase, date: date)
       else
-        raise ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
+        fail ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
       end
     end
 
@@ -55,7 +63,7 @@ module Timeprice
       when /\A\d{4}\z/         then "#{date}-06-30"
       when /\A\d{4}-\d{2}\z/   then "#{date}-15"
       when /\A\d{4}-\d{2}-\d{2}\z/ then date.to_s
-      else raise ArgumentError, "Invalid date for Point: #{date.inspect}"
+      else fail ArgumentError, "Invalid date for Point: #{date.inspect}"
       end
     end
   end

data/lib/timeprice/schema.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Timeprice
+  # Single source of truth for the on-disk v4 CPI/manifest format. Both the
+  # reader ({DataLoader}) and the writer (today: pipeline `CountryFile`)
+  # route through here so the schema lives in exactly one place.
+  module Schema
+    CURRENT_VERSION = 4
+    SUPPORTED_VERSIONS = [3, 4].freeze
+
+    KEY_SCHEMA_VERSION = "schema_version"
+    KEY_COUNTRY        = "country"
+    KEY_INDEX          = "index"
+    KEY_SERIES         = "series"
+    KEY_PROVENANCE     = "provenance"
+    KEY_PROVIDERS      = "providers"
+
+    GRANULARITIES = %i[monthly quarterly annual].freeze
+
+    BASE_YEAR_RE = /\A(?<period>.+?)=100(?:\s*\(rebased\s+(?<rebased>\d{4}-\d{2}-\d{2})\))?\z/
+
+    module_function
+
+    def supported?(version)
+      SUPPORTED_VERSIONS.include?(version)
+    end
+
+    def assert_supported!(version, path)
+      return if supported?(version)
+
+      fail UnsupportedSchemaVersion.new(version, path)
+    end
+
+    # Build a CPI payload ready for JSON.dump. Series keys are emitted in a
+    # stable order (annual, monthly[, quarterly]) so file diffs stay tight.
+    def dump_cpi(country:, base_year:, monthly:, annual:, providers:, provenance:, quarterly: {})
+      series = { "annual" => annual, "monthly" => monthly }
+      series["quarterly"] = quarterly unless quarterly.empty?
+      {
+        KEY_SCHEMA_VERSION => CURRENT_VERSION,
+        KEY_COUNTRY => country.to_s.upcase,
+        KEY_INDEX => serialise_base_year(base_year),
+        KEY_SERIES => series,
+        KEY_PROVENANCE => provenance,
+        KEY_PROVIDERS => providers,
+      }
+    end
+
+    # Validate a parsed payload (read from disk) against the schema, then
+    # return it unchanged. Raises UnsupportedSchemaVersion if the version
+    # field is missing or unknown.
+    def load_cpi(parsed, path:)
+      assert_supported!(parsed[KEY_SCHEMA_VERSION], path)
+      parsed
+    end
+
+    def serialise_base_year(str)
+      m = BASE_YEAR_RE.match(str.to_s)
+      if m
+        { "base_period" => m[:period], "rebased_at" => m[:rebased] }
+      else
+        { "base_period" => str.to_s, "rebased_at" => nil }
+      end
+    end
+
+    def deserialise_base_year(index)
+      return nil unless index.is_a?(Hash)
+
+      period = index["base_period"]
+      rebased = index["rebased_at"]
+      return nil if period.nil?
+
+      rebased ? "#{period}=100 (rebased #{rebased})" : "#{period}=100"
+    end
+  end
+end