{
  "$schema": "./score_v2_data_semantics.schema.json",
  "contract_version": 1,
  "methodology_version": "usd_impact_score_v2",
  "status": "supplemental_transparency_contract",
  "production_methodology_changed": false,
  "purpose": "Disclose the exact source-field, calendar, timestamp, and futures-series semantics used by the production pipeline.",
  "retrieval": {
    "yahoo": {
      "client": "yfinance",
      "frequency": "daily",
      "field": "Close",
      "auto_adjust": true,
      "threads": false,
      "intraday_timestamp_retained": false,
      "date_semantics": "Provider-returned daily date index; the pipeline does not retain an exchange settlement timestamp.",
      "rights_reference": "https://ranaroussi.github.io/yfinance/",
      "retention_policy": "No raw Yahoo response payload or complete Yahoo-derived value history is retained or publicly redistributed by the weekly workflow."
    },
    "fred": {
      "endpoint": "https://fred.stlouisfed.org/graph/fredgraph.csv?id={series}",
      "frequency": "daily",
      "date_field": "observation_date",
      "value_field": "the named FRED series column",
      "intraday_timestamp_retained": false,
      "date_semantics": "FRED observation date; the pipeline does not retain the provider publication timestamp.",
      "rights_reference": "https://fred.stlouisfed.org/docs/api/terms_of_use.html",
      "series_rights_status": "DGS2 and DGS10 are tagged Public Domain: Citation Requested on their FRED series pages; the mixed-source weekly workflow still does not archive raw provider responses."
    }
  },
  "alignment": {
    "join": "outer join across providers, sorted by date",
    "source_provenance_captured": "before forward fill",
    "forward_fill_limit_observations": 3,
    "weekly_rule": "W-FRI",
    "weekly_value": "last available aligned observation in the Friday-ended week",
    "incomplete_future_weeks_removed": true,
    "complete_case_required_for_score": true,
    "holiday_handling": "Different provider calendars are aligned by a maximum three-observation forward fill; release freshness limits still use each original provider observation date."
  },
  "futures": {
    "WTI": {
      "symbol": "CL=F",
      "series_semantics": "Yahoo Finance provider-defined continuous front-month futures history",
      "pipeline_controls_contract_selection": false,
      "pipeline_controls_roll_calendar": false,
      "pipeline_controls_back_adjustment": false
    },
    "GOLD": {
      "symbol": "GC=F",
      "series_semantics": "Yahoo Finance provider-defined continuous front-month futures history",
      "pipeline_controls_contract_selection": false,
      "pipeline_controls_roll_calendar": false,
      "pipeline_controls_back_adjustment": false
    },
    "replication_boundary": "A live cross-vendor reconstruction must not assume identical roll or revision history. Strict release bundles freeze the exact weekly levels actually used from 2026-08-28 onward."
  },
  "revision_policy": {
    "latest_history": "Current-vintage recalculation that may change when providers revise history or the full-sample normalization window expands.",
    "as_published_archive": "Dated release folders preserve published score outputs and commentary.",
    "strict_reproduction_bundle_required_from": "2026-08-28",
    "same_run_input_handoff_required_from": "2026-08-28",
    "complete_weekly_input_history_fingerprint": "SHA-256 for the canonical complete matrix and each driver is frozen in every strict reproduction bundle.",
    "complete_provider_derived_daily_history_fingerprint": "SHA-256 for the canonical pre-forward-fill daily matrix and each driver, limited to observations on or before the score week, is frozen in every strict reproduction bundle.",
    "original_transport_bytes_hashed": false,
    "raw_provider_payload_archive": "not_implemented",
    "rights_and_retention_reviewed_on": "2026-08-24",
    "retention_policy_document": "https://github.com/usdimpact/usd-impact-pipeline/blob/main/docs/source-retention-policy.md",
    "limitation": "The strict bundle preserves the latest calculation inputs, normalization moments, outputs and cryptographic fingerprints of both the same-run provider-derived daily history and complete weekly input history. The hashes begin after field selection and numeric parsing; original transport bytes are not hashed, complete provider-derived values are not published, and raw provider responses are not archived."
  },
  "vendor_resilience": {
    "alternative_vendor_in_production": false,
    "status": "not_implemented",
    "acceptance_requirement": "Any alternative source must document field, timezone, holiday, revision, and futures-roll equivalence before use."
  }
}