From ad21702ddd7e40012a3293651b0b8559c1c73132 Mon Sep 17 00:00:00 2001 From: Matt Spinola Date: Tue, 14 Jul 2026 17:56:34 -0400 Subject: [PATCH] docs: correct stale v2 migration status in config and README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The store was migrated to schema v2 by a full producer pass (2026-07-14), but two doc statements still described the pre-migration world: - config.py claimed the store "does not actually carry v2 shape until a full producer pass re-writes it" — no longer true. Reword to note the migration is done and that schema_version() reflects on-disk truth. - README described Volume_Reconstructed as "systematically higher than raw Volume." Verified against the store this is symbol-dependent: higher for products whose rolls spread volume across contracts, but roughly equal or lower for near-empty-back-month symbols like crypto (BTC/ETH reconstruct to ~0.98-1.00x raw). Reword to reflect that. Docs-only; no code behavior change. Store verified: schema_version=2, 84/84 price files carry reconstructed volume. Co-Authored-By: Claude Opus 4.8 --- README.md | 2 +- src/cotdata/config.py | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9638f39..5b15213 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ The primary source for price history (Norgate Data). Indexed by tz-naive `Date`. | `Close` | float | Settlement Close price. | | `Volume` | float | Continuous contract trading volume (front-month only). | | `Open Interest` | float | Continuous contract open interest. | -| `Volume_Reconstructed` | float | True market volume (sum of First and Second contract). Note: systematically higher than raw `Volume`, not a drop-in replacement. | +| `Volume_Reconstructed` | float | True market volume (sum of First and Second contract). Differs from raw `Volume` by symbol — typically higher for products whose rolls spread volume across contracts, but roughly equal or lower for symbols with a near-empty back month (e.g. crypto). Not a drop-in replacement. | | `Volume_Source` | string | `reconstructed` if First+Second available, `raw` fallback if not. | | `FirstVolume` / `SecondVolume` | float | Trading volume of the specific first and second expiring contracts. | | `FirstContract` / `SecondContract` | string | Contract names for the first and second expirations (e.g., `ES-2024H`). | diff --git a/src/cotdata/config.py b/src/cotdata/config.py index f301fda..1e302e4 100644 --- a/src/cotdata/config.py +++ b/src/cotdata/config.py @@ -4,8 +4,9 @@ # v2 — reconstructed volume promoted: prices carry Volume_Reconstructed / # Volume_Source, and get_prices(volume="reconstructed") serves them. The store -# does not actually carry v2 shape until a full producer pass re-writes it; see -# docs/plan_promote_reconstructed_volume.md for the rollout order. +# was migrated by a full producer pass (2026-07-14) and now carries v2 shape; +# schema_version() reflects the on-disk manifest, so a fresh/partial store can +# still read <2. See docs/plan_promote_reconstructed_volume.md for the rollout. SCHEMA_VERSION = 2