Freshness & quality
Every commodities.sh observation carries ruthless labels so agents never confuse weekly EIA stocks with monthly indicative metals or derived crack proxies.
What is freshness_class?
freshness_class describes the economic cadence of the print — eod, weekly, monthly, decree, and related classes. Weekly EIA inventories and annual USGS MCS must not be reasoned about as if they shared one clock.
What does quality mean?
quality is the trust tier: official (direct agency), indicative (compiled or pending license nuance), derived (computed with cited inputs), or delayed. Derived crack and crush always cite input observation IDs in provenance.
How should agents use license_tag and provenance?
license_tag encodes redistribution posture (fred_public, us_gov_public, usgs_public, and related). provenance includes retrieved_at, cache_hit, and cache_ttl_s so agents know when the server last fetched upstream.
Field reference
| Field | Meaning |
|---|---|
| freshness_class | eod | weekly | monthly | decree | … |
| quality | official | indicative | derived | delayed |
| license_tag | Redistribution posture (fred_public, usgs_public, …) |
| source | { name, series_id, url } |
| provenance | retrieved_at, cache_hit, cache_ttl_s |