timeprice 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b400f9dc1652d4476d884f59a2721e4f07338e76c5cc7afab50896267e1123c
-  data.tar.gz: 1a894e2464aa1f1495ddaa24c284b819a8afc07309cd3080f7c8c70744959ef2
+  metadata.gz: 6f5a76db32571e7ab2f09f9e22e1d90d420b5bdcf474baff6b523f2c8998c72b
+  data.tar.gz: 96e212aaa5aac2cfe4defc28364498ef49241de34161cb3e301f4886a19650d0
 SHA512:
-  metadata.gz: 1f2c0b9ae5a4f8de71bdfdfb28f911b676773d406f86149b0c12ad5fbeb002ad51e42d43ed9f21d41c6ddd1a5b2760c2df58796759f66e7b78ac0dc784cee971
-  data.tar.gz: 8dc9e2ff73ddf7d0126538794bb4612a8709881628b713a1e878fe8fba7eddd510597f5a4f0a07e8c9d3b63cc751880df9150db208616f7fc52306ae2474bd10
+  metadata.gz: 4148766e8c3dee2243ed933868d23cb2d79959db1581d07de654e1bab87325de98eacb2cd41200e1f765f3d94dde03472dc5d02a37e2e2f059fc8a651ac40666
+  data.tar.gz: a51e3132f616bc0e468b0f9afdff9ab71a2017abd25eed5ffd45cecc4c385d58f4670ffeeb5cc8bc5f4143f639a42d92f88a2d6e4f81957171d6c3207982d5ee

data/CHANGELOG.md

@@ -5,6 +5,61 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-11
+
+### Changed
+- **Schema v2 → v3.** Breaking change to the bundled data contract. v0.4.x
+  data files will not load on v0.5.0.
+  - New top-level `data/manifest.json` — single source of truth for which
+    countries and currencies the bundle supports. `Supported.countries` /
+    `Supported.currencies` derive from it at runtime; the hardcoded Ruby
+    constants `Supported::COUNTRIES` / `CURRENCIES` are gone. Custom callers
+    that referenced those constants must switch to the method form.
+  - CPI files use nested `series: { monthly, annual }` and a structured
+    `index: { base_period, rebased_at }` block in place of the freeform
+    `base_year` string. Top-level `source` and `updated_at` removed —
+    `providers[]` is the source of truth for provenance.
+  - FX year files now carry `provenance` + `providers` blocks, symmetric
+    with CPI.
+  - All annual FX (today only VND from World Bank) lives in
+    `data/fx/usd/_annual.json` — the single canonical source, every year.
+    Per-year files (`data/fx/usd/<year>.json`) hold daily rates only. Pre-1999
+    stub year files are gone. `Exchange.lookup_usd_base` collapses to a
+    two-tier chain (daily → annual fallback), one source per tier.
+
+## [0.4.0] - 2026-05-11
+
+### Changed
+- **Schema v1 → v2.** Two structural data-layer changes, bundled under a
+  single bump:
+  - FX year files gain an optional top-level `annual` block. World Bank's
+    annual VND/USD average is stored there exactly once per year instead of
+    being broadcast across every daily date key. `Exchange.lookup_usd_base`
+    falls back from daily to annual when no daily entry exists within ±7
+    days and tags the result with `Granularity::ANNUAL`. `Compare` merges
+    FX granularity with CPI granularity (worst-precision wins).
+  - CPI provenance moves from a per-period map (`{"2025-01": "bls", ...}`)
+    to a compact range list (`[{series, from, to, provider}, ...]`). Single
+    -provider files (US/UK/EU/JP) collapse to 1–2 ranges; VN keeps the
+    WB→IMF transition explicit. ~42 kb saved across the 5 CPI files; one
+    real US data gap at 2025-10 is now visible instead of buried.
+- `country_file.rb` rebase label now preserves the original base reference
+  alongside the rebase date (e.g. `"2010=100 (rebased 2026-05-11)"`).
+
+### Added
+- Multi-source CPI chain for Vietnam: IMF Data Portal CPI dataflow
+  (`api.imf.org`, SDMX 2.1) is the monthly primary; World Bank `FP.CPI.TOTL`
+  remains as the annual fallback. The on-disk `data/cpi/vn.json` gains two
+  additive fields — `provenance` (per-period source id) and `providers`
+  (per-source status array) — so consumers can see which upstream supplied
+  each datapoint. Schema version is unchanged; old readers ignore the new
+  fields. Other country files (US, UK, EU, JP) gain the same fields on the
+  next refresh.
+- Internal: `Sources::Provider` / `Sources::CountryFile` / `Sources::MergePolicy`
+  seam for layering multiple providers into a single country file with
+  per-period provenance. Designed so future fresher sources (e.g. JP via
+  e-Stat) can be added as one more entry without further plumbing.
+
 ## [0.3.0] - 2026-05-11
 
 ### Added

data/DATA_LICENSES.md

@@ -12,7 +12,8 @@ string.
 | UK Office for National Statistics | `D7BT` (UK CPI all-items) | Open Government Licence v3.0 | https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/ | Contains public sector information licensed under the Open Government Licence v3.0 |
 | Eurostat | `prc_hicp_midx` (Euro area HICP) | Eurostat reuse policy — free reuse with source attribution | https://ec.europa.eu/eurostat/about-us/policies/copyright | Source: Eurostat |
 | 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) | 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 |
 | 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 |
 

data/README.md

@@ -98,11 +98,12 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | United Kingdom | GBP | ONS CPI all-items (`D7BT`) | Monthly + annual | 1988-01 → present |
 | 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 | World Bank `FP.CPI.TOTL` | Annual | 1995 → 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`) broadcast to
-every day in the year, from 1983 → present.
+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.
 
 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.
@@ -258,13 +259,28 @@ license — see `DATA_LICENSES.md` and `NOTICE` for the full table and license U
 - **UK CPI:** Contains public sector information licensed under the Open Government Licence v3.0.
 - **Eurozone HICP:** Source: Eurostat (reuse permitted with attribution).
 - **Japan CPI (fallback):** Source: World Bank, FP.CPI.TOTL (CC BY 4.0).
-- **Vietnam CPI:** Source: World Bank, FP.CPI.TOTL (CC BY 4.0).
+- **Vietnam CPI:** Sources: IMF Data Portal CPI dataflow (monthly primary); World Bank, FP.CPI.TOTL (annual fallback, CC BY 4.0).
 - **FX rates:** European Central Bank reference rates via Frankfurter.
 - **VND FX (annual broadcast):** World Bank, PA.NUS.FCRF (CC BY 4.0).
 
 If you redistribute results derived from this gem, reproduce the relevant attribution
 strings. `timeprice sources` prints them in plain text and as JSON.
 
+## Data format
+
+Bundled data lives under `data/` in schema v3 and is self-describing:
+
+- `data/manifest.json` — the supported set (countries, currencies, FX years).
+- `data/cpi/<country>.json` — CPI for one country: `series.{monthly,annual}`,
+  structured `index` block, `provenance` ranges, `providers` attribution.
+- `data/fx/usd/<year>.json` — daily USD-base FX rates for one year (one file
+  per year, EUR/GBP/JPY).
+- `data/fx/usd/_annual.json` — annual USD-base FX rates across all years for
+  currencies sourced at annual resolution (today only VND). Used as the
+  fallback tier when no daily rate covers the requested date.
+
+`scripts/check_schema_stability.rb` enforces the shape in CI.
+
 ## Author
 
 Built by [Patrick](https://github.com/patrick204nqh).