timeprice 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f5a76db32571e7ab2f09f9e22e1d90d420b5bdcf474baff6b523f2c8998c72b
-  data.tar.gz: 96e212aaa5aac2cfe4defc28364498ef49241de34161cb3e301f4886a19650d0
+  metadata.gz: 5f350843e8e12653e2f798d8f9afec193001e911e0f36910d0473724f33d79f8
+  data.tar.gz: 3d1107eb101dd95ec6c2203fe6f1843f9249cf5046cf838577094c67a0fe63c0
 SHA512:
-  metadata.gz: 4148766e8c3dee2243ed933868d23cb2d79959db1581d07de654e1bab87325de98eacb2cd41200e1f765f3d94dde03472dc5d02a37e2e2f059fc8a651ac40666
-  data.tar.gz: a51e3132f616bc0e468b0f9afdff9ab71a2017abd25eed5ffd45cecc4c385d58f4670ffeeb5cc8bc5f4143f639a42d92f88a2d6e4f81957171d6c3207982d5ee
+  metadata.gz: a7efbb6d151b4fd4c9c6d4697fc9c755c9a0d2e6b8e1e32d828a1416737dbfbd00d9143c64edde191eaea3f7f758b96ac1d4b93c9f765fbc5d0993bf68b0be7a
+  data.tar.gz: 3a5b598b62cf93b992ed4ba5d069f84475c91a0be636600451fb3247caaa5c494c44b39268ed5e6107c34f923606521d42374d3300de42ad5a7449f53ae37e39

data/CHANGELOG.md

@@ -5,6 +5,36 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-12
+
+### Added
+- **Five new countries: AU, CA, KR, CN, RU.** CPI + FX coverage:
+  - AU (Australia): quarterly CPI from ABS 6401.0, annual baseline from World
+    Bank `FP.CPI.TOTL`; AUD daily FX from Frankfurter.
+  - CA (Canada): monthly CPI from Statistics Canada WDS (table 18-10-0004-01),
+    annual baseline from World Bank; CAD daily FX from Frankfurter.
+  - KR (Korea, Rep.): monthly CPI from IMF Data Portal CPI dataflow, annual
+    baseline from World Bank; KRW daily FX from Frankfurter. (KOSIS Open API
+    is a future upgrade path — see `scripts/sources/kosis.rb`.)
+  - CN (China): annual CPI from World Bank, monthly layered from IMF Data
+    Portal; CNY daily FX from Frankfurter.
+  - RU (Russia): annual CPI from World Bank, monthly layered from IMF; RUB FX
+    from IMF IFS `ENDA_XDC_USD_RATE` written as annual averages to
+    `_annual.json` (Frankfurter dropped RUB after the ECB suspended reference
+    rates in March 2022, so daily RUB is intentionally not bundled).
+- `KRW` added to `Supported::ZERO_DECIMAL_CURRENCIES`.
+
+### Changed
+- **Schema v3 → v4.** Backward-compatible bump:
+  - CPI files gain an optional `series.quarterly` block (keyed `YYYY-Qn`)
+    alongside `series.monthly` and `series.annual`. Files without quarterly
+    data are byte-identical to v3 layout other than the version field.
+  - `DataLoader` accepts both v3 and v4 files; new writes are v4.
+  - `Granularity` gains `:quarterly`, `:annual_from_quarterly_avg`,
+    `:quarterly_from_annual_fallback`, and `:monthly_from_quarterly_fallback`.
+    `CpiLookup` resolves "YYYY-Qn" keys and falls back monthly → quarterly →
+    annual.
+
 ## [0.5.0] - 2026-05-11
 
 ### Changed

data/DATA_LICENSES.md

@@ -14,8 +14,15 @@ string.
 | World Bank | `FP.CPI.TOTL` (JP CPI fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 | World Bank | `FP.CPI.TOTL` (VN CPI, annual fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 | International Monetary Fund | CPI dataflow `VNM.CPI._T.IX.M` via IMF Data Portal (VN CPI, monthly primary) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
-| European Central Bank (via Frankfurter) | Daily reference rates, USD base, EUR/GBP/JPY | ECB reference rates — free reuse; Frankfurter is a non-commercial republisher with no separate license | https://www.ecb.europa.eu/services/disclaimer/html/index.en.html | FX data: European Central Bank reference rates via Frankfurter |
+| European Central Bank (via Frankfurter) | Daily reference rates, USD base, EUR/GBP/JPY/AUD/CAD/KRW/CNY | ECB reference rates — free reuse; Frankfurter is a non-commercial republisher with no separate license | https://www.ecb.europa.eu/services/disclaimer/html/index.en.html | FX data: European Central Bank reference rates via Frankfurter |
 | World Bank | `PA.NUS.FCRF` (VND annual average FX, broadcast daily) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | VND FX: World Bank, PA.NUS.FCRF |
+| Australian Bureau of Statistics | `CPI` dataflow, key `3.10001.10.50.Q` (AU CPI, quarterly, all groups, weighted average of eight capital cities) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://www.abs.gov.au/website-privacy-copyright-and-disclaimer/copyright-and-creative-commons | Source: Australian Bureau of Statistics, 6401.0 Consumer Price Index |
+| Statistics Canada | Table 18-10-0004-01, vector `v41690973` (CA CPI, monthly, all-items, not seasonally adjusted) | Statistics Canada Open License | https://www.statcan.gc.ca/en/reference/licence | Source: Statistics Canada, table 18-10-0004-01 |
+| International Monetary Fund | CPI dataflow `KOR.CPI._T.IX.M` (KR CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | CPI dataflow `CHN.CPI._T.IX.M` (CN CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | CPI dataflow `RUS.CPI._T.IX.M` (RU CPI, monthly) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
+| International Monetary Fund | IFS dataflow `M.RUS.ENDA_XDC_USD_RATE` (RUB/USD, period-average, annual mean written to `_annual.json`) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF International Financial Statistics |
+| World Bank | `FP.CPI.TOTL` (AU/CA/KR/CN/RU CPI annual baselines) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
 
 ## Notes
 
@@ -25,6 +32,14 @@ string.
 - The Vietnam VND FX series is the **annual average** broadcast to every day in
   the year — it is intentionally not a daily market rate. Do not use it for
   intraday or trade-execution purposes.
+- **RUB FX is annual-only** (from IMF IFS period averages). Frankfurter (ECB)
+  stopped publishing RUB daily reference rates in March 2022 after the ECB
+  suspended the rate, and no other free, no-API-key daily source covers the
+  full series. Daily RUB lookups fall back to the annual average and the
+  result is tagged so consumers can detect the degradation.
+- **AU CPI is published quarterly only.** Lookups against "YYYY-MM" keys for
+  Australia fall back to the quarter that contains the month, and the result
+  is tagged `:monthly_from_quarterly_fallback`.
 - Eurostat HICP is harmonized across the Eurozone and is **not** the same as
   any national CPI. We use it for the `EU` country code; national CPIs are out
   of scope for v0.1.

data/README.md

@@ -99,11 +99,19 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | Eurozone (EA) | EUR | Eurostat HICP (`prc_hicp_midx`) | Monthly + annual | 1996-01 → present |
 | Japan | JPY | World Bank `FP.CPI.TOTL` (fallback) | Annual | 1960 → 2024 |
 | Vietnam | VND | IMF Data Portal CPI dataflow (monthly primary) + World Bank `FP.CPI.TOTL` (annual fallback) | Monthly + annual | 1995 → present |
-
-**FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY**, daily
-1999 → present. **VND** uses the World Bank annual average (`PA.NUS.FCRF`), one value
-per year, from 1983 → present. VND results are tagged `granularity: :annual` so callers
-know they got the annual fallback rather than a daily rate.
+| Australia | AUD | ABS 6401.0 (quarterly) + World Bank `FP.CPI.TOTL` (annual baseline) | Quarterly + annual | 1948-Q3 → present |
+| Canada | CAD | Statistics Canada WDS (table 18-10-0004-01, vector `v41690973`) + World Bank annual baseline | Monthly + annual | 1914-01 → present |
+| Korea (Rep.) | KRW | IMF Data Portal CPI dataflow + World Bank annual baseline | Monthly + annual | 1990-01 → present |
+| China | CNY | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1990-01 → present |
+| Russia | RUB | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1992-01 → present |
+
+**FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY / AUD /
+CAD / KRW / CNY**, daily 1999 → present. **VND** uses the World Bank annual average
+(`PA.NUS.FCRF`), one value per year, from 1983 → present. **RUB** uses IMF IFS
+period-average rates as annual means (`ENDA_XDC_USD_RATE`) — Frankfurter dropped RUB
+after the ECB suspended its reference rate in March 2022, so daily RUB is intentionally
+not bundled. Annual-fallback results (VND, RUB) are tagged `granularity: :annual` so
+callers know they did not get a daily rate.
 
 Triangulated cross-rates (e.g. GBP → JPY) go through USD on the same effective date.
 Weekend/holiday dates fall back up to 7 days to the nearest prior trading day.
@@ -223,7 +231,7 @@ namespace :inflation do
   desc "Print 1990→today inflation for the supported countries"
   task :report do
     today = Date.today.strftime("%Y-%m")
-    %w[US UK EU JP VN].each do |c|
+    %w[US UK EU JP VN AU CA KR CN RU].each do |c|
       r = Timeprice.inflation(amount: 100, from: "1990", to: today, country: c)
       puts "#{c}: 100 in 1990 → #{r.amount.round(2)} in #{today} (#{r.granularity})"
     end

data/data/cpi/eu.json

@@ -26,7 +26,7 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3,
+  "schema_version": 4,
   "series": {
     "annual": {
       "1996": 71.742,

data/data/cpi/jp.json

@@ -20,7 +20,7 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3,
+  "schema_version": 4,
   "series": {
     "annual": {
       "1960": 18.9725686020745,

data/data/cpi/uk.json

@@ -26,7 +26,7 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3,
+  "schema_version": 4,
   "series": {
     "annual": {
       "1988": 49.6,

data/data/cpi/us.json

@@ -32,7 +32,7 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3,
+  "schema_version": 4,
   "series": {
     "annual": {
       "1990": 130.658,

data/data/cpi/vn.json

@@ -38,7 +38,7 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3,
+  "schema_version": 4,
   "series": {
     "annual": {
       "1995": 21.083683,

data/data/fx/usd/1999.json

@@ -1318,6 +1318,6 @@
       "JPY": 102.26
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 1999
 }

data/data/fx/usd/2000.json

@@ -1298,6 +1298,6 @@
       "JPY": 114.91
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2000
 }

data/data/fx/usd/2001.json

@@ -1293,6 +1293,6 @@
       "JPY": 130.86
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2001
 }

data/data/fx/usd/2002.json

@@ -1298,6 +1298,6 @@
       "JPY": 118.61
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2002
 }

data/data/fx/usd/2003.json

@@ -1298,6 +1298,6 @@
       "JPY": 106.93
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2003
 }

data/data/fx/usd/2004.json

@@ -1318,6 +1318,6 @@
       "JPY": 102.53
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2004
 }

data/data/fx/usd/2005.json

@@ -1308,6 +1308,6 @@
       "JPY": 117.74
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2005
 }

data/data/fx/usd/2006.json

@@ -1298,6 +1298,6 @@
       "JPY": 119.16
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2006
 }

data/data/fx/usd/2007.json

@@ -1298,6 +1298,6 @@
       "JPY": 112.04
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2007
 }

data/data/fx/usd/2008.json

@@ -1303,6 +1303,6 @@
       "JPY": 90.64
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2008
 }

data/data/fx/usd/2009.json

@@ -1303,6 +1303,6 @@
       "JPY": 92.43
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2009
 }

data/data/fx/usd/2010.json

@@ -1313,6 +1313,6 @@
       "JPY": 81.31
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2010
 }

data/data/fx/usd/2011.json

@@ -1308,6 +1308,6 @@
       "JPY": 77.44
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2011
 }

data/data/fx/usd/2012.json

@@ -1303,6 +1303,6 @@
       "JPY": 86.11
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2012
 }

data/data/fx/usd/2013.json

@@ -1298,6 +1298,6 @@
       "JPY": 104.94
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2013
 }

data/data/fx/usd/2014.json

@@ -1298,6 +1298,6 @@
       "JPY": 119.62
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2014
 }

data/data/fx/usd/2015.json

@@ -1303,6 +1303,6 @@
       "JPY": 120.39
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2015
 }

data/data/fx/usd/2016.json

@@ -1308,6 +1308,6 @@
       "JPY": 117.07
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2016
 }

data/data/fx/usd/2017.json

@@ -1298,6 +1298,6 @@
       "JPY": 112.57
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2017
 }

data/data/fx/usd/2018.json

@@ -1298,6 +1298,6 @@
       "JPY": 109.91
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2018
 }

data/data/fx/usd/2019.json

@@ -1298,6 +1298,6 @@
       "JPY": 108.55
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2019
 }

data/data/fx/usd/2020.json

@@ -1308,6 +1308,6 @@
       "JPY": 103.08
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2020
 }

data/data/fx/usd/2021.json

@@ -1313,6 +1313,6 @@
       "JPY": 115.12
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2021
 }

data/data/fx/usd/2022.json

@@ -1308,6 +1308,6 @@
       "JPY": 131.88
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2022
 }

data/data/fx/usd/2023.json

@@ -1298,6 +1298,6 @@
       "JPY": 141.48
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2023
 }

data/data/fx/usd/2024.json

@@ -1303,6 +1303,6 @@
       "JPY": 156.95
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2024
 }

data/data/fx/usd/2025.json

@@ -1298,6 +1298,6 @@
       "JPY": 156.67
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2025
 }

data/data/fx/usd/2026.json

@@ -463,6 +463,6 @@
       "JPY": 156.76
     }
   },
-  "schema_version": 3,
+  "schema_version": 4,
   "year": 2026
 }

data/data/fx/usd/_annual.json

@@ -141,5 +141,5 @@
       "status": "ok"
     }
   ],
-  "schema_version": 3
+  "schema_version": 4
 }

data/data/manifest.json

@@ -86,5 +86,5 @@
     ]
   },
   "generated_at": "2026-05-11",
-  "schema_version": 3
+  "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/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.dig("series", "monthly") || {}
-      @annual  = data.dig("series", "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

@@ -8,7 +8,11 @@ module Timeprice
   # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
   # {DataLoader.data_root=}.
   module DataLoader
-    SUPPORTED_SCHEMA_VERSION = 3
+    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__)
 
@@ -114,7 +118,7 @@ module Timeprice
       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

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

@@ -27,11 +27,11 @@ module Timeprice
 
     # 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 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

data/lib/timeprice/supported.rb

@@ -10,7 +10,7 @@ module Timeprice
   module Supported
     # Currencies with no minor unit — formatted as whole numbers. This is
     # ISO 4217 metadata, not bundled data, so it stays hardcoded.
-    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+    ZERO_DECIMAL_CURRENCIES = %w[JPY KRW VND].freeze
 
     module_function
 

data/lib/timeprice/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Patrick