{"ok":true,"catalog":{"version":"1.0","generated_at":"2026-07-13T00:19:16.741756+00:00"},"query":{"view":"all","q":null,"domain":null,"status":null},"summary":{"total_sources":282,"total_tools":38,"sources_by_domain":{"commercial":10,"hospital":15,"provider_identity":38,"medicare":148,"drug":42,"curated":16,"provenance":4,"state":9},"sources_by_stage":{"curated":7,"mart":9,"index":1,"dim":52,"raw":2,"silver":172,"semantic_view":32,"reference":3,"registry":4},"sources_by_status":{"partial":56,"live":221,"planned":4,"design_locked":1},"sources_with_documented_row_count":112,"tools_linked_to_a_source":27,"tools_unlinked":11,"tools_by_layer":{"L2":33,"L1":5},"warnings_count":1,"live_inspection":{"glue_available":true,"postgres_available":false}},"warnings":["Postgres inspection skipped: VLADA_CATALOG_PG_DSN not set"],"domains":{"commercial":{"source_count":10,"tool_count":12,"sources":["vlada_curated.fact_rate","vlada_curated.mart_rate_by_code","vlada_curated.idx_rate_lookup","vlada_curated.dim_payer","s3://vlada-platform-raw/commercial_v2","vlada_curated.rate_provider_edge","vlada_curated.mart_rate_by_entity","medicare_silver.fact_idr_determination","medicare_silver.fact_tc_puf_issuer_claims","medicare_silver.fact_rate_puf"],"tools":["benchmark_code","compare_rates","compute_median_rate","explain_rate","get_negotiated_rate","get_rate_with_provenance","lookup_rates_for_npi","lookup_rates_for_tin","plan_commercial_price_proof","prove_commercial_price","query_substrate","replay_commercial_price_proof"]},"curated":{"source_count":16,"tool_count":14,"sources":["vlada_curated.mart_unified_pricing","drug_silver.dim_icd10cm","drug_silver.dim_icd10pcs","medicare_silver.dim_code_validity","medicare_silver.cpt_revcode_modal","vlada_curated.dim_code","vlada_curated.dim_geography","vlada_curated.dim_code_billing_class","vlada_curated.dim_state_metric","vlada_curated.dim_taxonomy_procedures","vlada_curated.agg_county_intelligence","vlada_curated.agg_care_site_payer_coverage","vlada_curated.agg_county_payer_landscape","vlada_curated.agg_state_payer_roster","vlada_curated.fact_policy_document","vlada_curated.fact_policy_doc_chunk"],"tools":["compare_hospital_to_payer_rates","county_intelligence","county_price_options","cross_source_rate_distribution","describe_data_source","describe_schema","fetch_query","find_data_sources","plan_answerability","poll_query","query","search_tools","state_expert","submit_query"]},"drug":{"source_count":42,"tool_count":0,"sources":["drug_silver.fact_drug_acquisition_cost","drug_silver.fact_drug_asp_quarterly#drug_asp","drug_silver.fact_drug_asp_quarterly","drug_silver.fact_form5500_filing","drug_silver.fact_form5500_service_provider","drug_silver.fact_drug_consumer_price","drug_silver.fact_drug_hcai_sb17_wac_increase","drug_silver.fact_drug_reimbursement#ira_mfp","drug_logical.fact_drug_formulary_scaffold","drug_silver.fact_drug_formulary","drug_silver.fact_drug_formulary_excluded","drug_silver.dim_part_d_plan","drug_silver.fact_part_d_plan_service_area","drug_silver.fact_part_d_plan_cost_share","drug_silver.fact_part_d_plan_drug_pricing","drug_silver.dim_orange_book_product","drug_logical.dim_purple_book_product_reference","drug_silver.dim_purple_book_product","drug.dea_controlled_substances","drug_silver.dim_dea_ndc_schedule","drug_silver.fact_drug_payment_to_prescriber","drug_silver.dim_drug","drug_silver.fact_drug_spending_part_d","drug_silver.fact_part_d_prescriber","drug_silver.fact_drug_spending_part_b","drug_silver.fact_drug_va_fss_price","drug_silver.fact_drug_medicaid_rebate_product","drug_silver.fact_drug_medicaid_utilization","drug_silver.fact_drug_shortage","drug_silver.fact_drug_recall","drug_silver.fact_fda_warning_letter","drug_silver.dim_rxclass_class","drug_silver.fact_rxclass_membership","drug_silver.fact_orange_book_patent","drug_silver.fact_orange_book_exclusivity","drug_silver.dim_drug_label","drug_silver.dim_drug_application","drug_silver.dim_dmf","drug_silver.fact_drug_clinical_trial","drug_silver.fact_form5500_service_provider_code","drug_silver.fact_drug_discarded_units","drug_silver.fact_faers_drug"],"tools":[]},"hospital":{"source_count":15,"tool_count":12,"sources":["vlada_curated.fact_hospital_chargemaster","s3://vlada-platform-raw/hospital","medicare_silver.fact_hospital_quality_measure","medicare_silver.dim_hospital_quality","medicare_silver.fact_inpatient_payment_by_geo","medicare_silver.fact_outpatient_payment_by_geo","vlada_curated.vw_fact_hospital_chargemaster_comparable","vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_fact_hospital_chargemaster_current","vlada_curated.vw_fact_hospital_chargemaster_validated","vlada_curated.fact_hospital_comparability_mat","vlada_curated.mart_hospital_cell","medicare_silver.fact_hospital_service_area","medicare_silver.fact_hrrp","medicare_silver.fact_hvbp"],"tools":["care_site_price","compare_hospital_rates","compare_hospital_to_commercial","county_expert","fair_rbp_book","fair_rbp_price","get_hospital_chargemaster","plan_hospital_price","prove_hospital_price","replay_hospital_price","state_agent","state_ingest"]},"medicare":{"source_count":148,"tool_count":0,"sources":["medicare_silver.medicare_physician_fee_schedule","medicare_silver.medicare_opps_rates","drug_silver.dim_msdrg","medicare_silver.medicare_asc_rates","medicare_silver.medicare_clfs_rates","medicare_silver.ma_county_ratebook","medicare_silver.stars_ratings_summary","medicare_silver.stars_ratings_measure","medicare_silver.stars_cutpoints","medicare_silver.stars_cai","medicare_silver.stars_contracts","medicare_silver.dim_stars_measures","medicare_silver.dim_stars_methodology","medicare_silver.dim_stars_measure_crosswalk","medicare_silver.hedis_general","medicare_silver.hedis_hos_frm","medicare_silver.hedis_hos_mui","medicare_silver.hedis_hos_oto","medicare_silver.hedis_hos_pao","medicare_silver.hedis_measures","medicare_silver.hedis_national_rates","medicare_silver.hedis_rau_measures","medicare_silver.hedis_service_area","medicare_silver.ma_contract_service_area","medicare_silver.ma_state_county_penetration","medicare_silver.mpf_benefit_summary_annual","medicare_silver.pbp_changelog","medicare_silver.pbp_field_dictionary","medicare_silver.pbp_mrx","medicare_silver.pbp_mrx_gap_coverage","medicare_silver.pbp_mrx_p","medicare_silver.pbp_mrx_tier","medicare_silver.pbp_plan_area","medicare_silver.pbp_plan_region_area","medicare_silver.pbp_sas_schema","medicare_silver.pbp_section_a","medicare_silver.pbp_section_b10_amb_trans","medicare_silver.pbp_section_b11_dme_prosth_orth_sup","medicare_silver.pbp_section_b12_renal_dialysis","medicare_silver.pbp_section_b14_preventive","medicare_silver.pbp_section_b15_partb_rx_drugs","medicare_silver.pbp_section_b19_model_test","medicare_silver.pbp_section_b1a_inpat_hosp","medicare_silver.pbp_section_b1b_inpat_hosp_psych","medicare_silver.pbp_section_b20","medicare_silver.pbp_section_b2_snf","medicare_silver.pbp_section_b3_cardiac_rehab","medicare_silver.pbp_section_b3_corf","medicare_silver.pbp_section_b4_emerg_urgent","medicare_silver.pbp_section_b5_partial_hosp","medicare_silver.pbp_section_b6_home_health","medicare_silver.pbp_section_b7_health_prof","medicare_silver.pbp_section_b8_clin_diag_ther","medicare_silver.pbp_section_b9_outpat_hosp","medicare_silver.pbp_section_c","medicare_silver.pbp_section_c_oon","medicare_silver.pbp_section_c_pos","medicare_silver.pbp_section_d","medicare_silver.pbp_section_d_oon","medicare_silver.pbp_section_d_opt","medicare_silver.pbp_vbid_overlay","medicare_silver.snp_data","medicare_semantic.vw_pbp_b19_combined_package","medicare_semantic.vw_pbp_cardiac_pulmonary_rehab","medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic","medicare_semantic.vw_pbp_dental","medicare_semantic.vw_pbp_dme","medicare_semantic.vw_pbp_emergency_urgent","medicare_semantic.vw_pbp_health_professionals","medicare_semantic.vw_pbp_hearing","medicare_semantic.vw_pbp_home_health","medicare_semantic.vw_pbp_inpatient_hospital","medicare_semantic.vw_pbp_inpatient_psychiatric","medicare_semantic.vw_pbp_moop","medicare_semantic.vw_pbp_otc","medicare_semantic.vw_pbp_outpatient_hospital","medicare_semantic.vw_pbp_partb_rx_drugs","medicare_semantic.vw_pbp_partd_drugs","medicare_semantic.vw_pbp_partd_tier","medicare_semantic.vw_pbp_partial_hospitalization","medicare_semantic.vw_pbp_preventive","medicare_semantic.vw_pbp_renal_dialysis","medicare_semantic.vw_pbp_section_c_pos_oon","medicare_semantic.vw_pbp_snf","medicare_semantic.vw_pbp_supplemental_other","medicare_semantic.vw_pbp_transportation","medicare_semantic.vw_pbp_vision","medicare_semantic.vw_pbp_benefits","medicare_silver.enrollment_monthly_county","medicare_silver.enrollment_monthly_plan","medicare_silver.plan_crosswalks_annual","medicare_silver.monthly_contract_enrollment_summary","medicare_silver.ma_mlr","medicare_silver.hospital_cost_report_overall","medicare_silver.hospital_cost_report_dept","medicare_silver.facility_cost_report_unit","medicare_silver.facility_cost_report_ccr","medicare_silver.hospital_outpatient_volume","medicare_silver.hcpcs_cost_center_crosswalk","medicare_silver.ma_plan_payment_part_c","medicare_silver.ma_plan_payment_part_d","medicare_silver.ma_plan_payment_county","medicare_silver.dim_hcc_coefficients","medicare_silver.dim_icd10_hcc_crosswalk","medicare_silver.landscape_all","medicare_silver.pbp_section_b13_other_services","medicare_silver.pbp_section_b16_dental","medicare_silver.pbp_section_b17_eye_exams_wear","medicare_silver.pbp_section_b18_hearing_exams_aids","vlada.rbp.ref.ipps_wage_index_2026","medicare_silver.fact_dme_payment_by_geo","medicare_silver.fact_physician_payment_by_geo","medicare_silver.dim_ipps_base_rate","medicare_silver.medicare_gpci_locality","medicare_silver.medicare_conversion_factor","medicare_silver.dim_anesthesia_base_unit","medicare_silver.medicare_county_to_locality","medicare_silver.medicare_zip_to_locality","medicare_silver.medicare_zip5_locality","vlada_curated.vw_medicare_benchmark","medicare_silver.landscape_ma_all","medicare_silver.mpf_optional_supplemental_annual","medicare_silver.fact_medicare_geo_variation","medicare_silver.fact_esrd_qip","medicare_silver.ncci_ptp","medicare_silver.medicare_pfs_indicators","medicare_silver.fact_physician_by_provider_service","medicare_silver.fact_inpatient_by_provider_service","medicare_silver.fact_outpatient_by_provider_service","medicare_silver.fact_dme_by_supplier_service","medicare_silver.fact_clfs_private_payer_rate","medicare_silver.fact_market_saturation","medicare_silver.fact_post_acute_utilization","medicare_silver.fact_aco_participant","medicare_silver.fact_qpp_experience","medicare_silver.fact_medicaid_managed_care","medicare_silver.fact_psps","medicare_silver.fact_hcahps","medicare_silver.fact_hospice_quality","medicare_silver.fact_home_health_quality","medicare_silver.fact_nursing_home_quality","medicare_silver.fact_ambulance_fee_schedule","medicare_silver.fact_hospice_pps_rate","medicare_silver.fact_irf_pps_cmg_weight","medicare_silver.fact_hh_pdgm_weight","medicare_silver.fact_fqhc_pps_rate","medicare_silver.fact_snf_pdpm_rate","medicare_silver.fact_ltch_pps_drg_weight"],"tools":[]},"provenance":{"source_count":4,"tool_count":0,"sources":["dim_substrate_mrf_version","medicare_source_registry_cache","drug_source_registry_cache","dim_mrf_version"],"tools":[]},"provider_identity":{"source_count":38,"tool_count":0,"sources":["vlada_curated.provider_facility_xref","vlada_curated.dim_provider","vlada_curated.dim_provider_service","vlada_curated.dim_facility","vlada_curated.dim_clia_lab","vlada_curated.dim_asc","vlada_curated.dim_dialysis_facility","medicare_silver.dim_imaging_facility","drug_silver.dim_facility_affiliation","vlada_curated.dim_hospital_external","drug_silver.dim_nucc_taxonomy","medicare_silver.dim_snf","medicare_silver.dim_hha","medicare_silver.dim_hospice","medicare_silver.dim_rhc","medicare_silver.dim_fqhc","medicare_silver.dim_irf","medicare_silver.dim_ltch","drug_silver.dim_oig_leie","drug_silver.dim_hhs_oig_cia","drug_silver.dim_hrsa_covered_entity","drug_silver.fact_hrsa_ce_npi","vlada_curated.dim_care_site","vlada_curated.dim_ccn_cbsa","vlada_curated.dim_health_system","vlada_curated.dim_hospital_system","vlada_curated.dim_provider_facility_affiliation","vlada_curated.fact_care_site_verification","vlada_curated.vw_care_site_verified","vlada_curated.care_site_geo","medicare_silver.fact_provider_ownership","medicare_silver.dim_dialysis_facility_quality","medicare_silver.fact_pecos_enrollment","medicare_silver.facility_npi_ccn_xref","medicare_silver.fact_provider_of_services","medicare_silver.dim_mdpp_supplier","medicare_silver.fact_hpsa","drug_silver.dim_device_udi"],"tools":[]},"state":{"source_count":9,"tool_count":0,"sources":["vlada_curated.fact_state_medicaid_rate","vlada_curated.fact_md_hscrc_unit_rate","vlada_curated.fact_ma_chia_relative_price","vlada_curated.fact_ct_medicaid_provider_rate","vlada_curated.fact_ct_medicaid_drg_weight","vlada_curated.fact_md_hscrc_monthly_rev_vol","vlada_curated.fact_ma_chia_revenue_cost_ratio","vlada_curated.fact_ct_hospital_cost_to_charge","vlada_curated.fact_nj_hospital_financials"],"tools":[]}},"counts":{"sources":282,"tools":38},"sources":[{"source_id":"commercial_fact_rate","source_fqn":"vlada_curated.fact_rate","title":"Commercial negotiated rates (TiC)","domain":"commercial","stage":"curated","status":"partial","grain":"One row per (payer, plan, NPI, code, modifier, billing_class, POS, negotiated_type) at a snapshot.","description":"Cleaned commercial-insurer negotiated rates extracted from payer Transparency-in-Coverage machine-readable files. The substrate of \"what does this payer actually pay this provider for this code.\"","identity_key":"npi","row_count":null,"last_updated":"2026-06-15","freshness_sla":"Payers publish monthly (1st per CMS rule); extracted within ~7 days.","recollection":{"cadence":"monthly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Per-payer vintage is tracked in dim_substrate_mrf_version (content_sha256), not a column on fact_rate; extraction lags the monthly publish by ~7 days."]},"raw_queryable_via":"Athena workgroup vlada-analytics: vlada_curated.fact_rate (always filter ghost_rate_score < 0.5)","commercial_terms":"Public TiC files; redistributable as cleaned substrate.","provenance_chain_ref":"dim_substrate_mrf_version[substrate=commercial] (schema/migrations/033_dim_commercial_mrf_version.sql)","context_doc_path":"docs/context_library/commercial/fact_rate.md","known_gaps":["Extracted but not served as of 2026-06-15: UHC, Florida Blue, BCBS RI, BCBS LA, BCBS MS, and BCBS NC; BCBS MA and BCBS AR are partial extracts.","~33 payer profiles discovered but not extracted/currently refreshed; largest remaining not-run mega-nationals are Elevance, Aetna/CVS, and HCSC.","~92% of raw rates are ghost rates; must filter ghost_rate_score >= 0.5.","Provider-groups are rate-scoped not network-scoped (~1000x repetition)."],"notes":"Current commercial truth packet v5 has 30/46 configured payer/network profiles indexed/live: amerihealth_caritas, amerihealth_nj, bcbs_id, bcbs_sc, carefirst, centene, cigna, emblemhealth, excellus, fallon, geisinger, health_new_england, health_partners, highmark, johns_hopkins_hc, kaiser, la_care, mclaren_health_plan, medical_mutual, molina, mvp, premera, priority_health, priority_health_via_cigna, quartz, sentara_health_plans, summacare, the_health_plan, tufts, and wellmark. Excellus/MVP/Quartz ledger backfill is closed; Highmark required G4.5 hot indexes. NEVER aggregate across modifier groups (rate-component splitter).","tools":["benchmark_code","compare_rates","get_negotiated_rate","get_rate_with_provenance","lookup_rates_for_npi","lookup_rates_for_tin","plan_commercial_price_proof","prove_commercial_price","replay_commercial_price_proof"]},{"source_id":"commercial_mart_rate_by_code","source_fqn":"vlada_curated.mart_rate_by_code","title":"Code-keyed commercial rate serving mart","domain":"commercial","stage":"mart","status":"partial","grain":"One row per fact_rate row (payer, state, rate_id), projected and partition-pruned by (payer_id, state, code_prefix).","description":"Gold serving mart shaped for cross-payer market queries — \"what does code X cost across payers in state Y?\". Pure projection from fact_rate (no edge join), partitioned by (payer_id, state, code_prefix). Backs compute_median_rate (code x state x payer rollups) and explain_rate (single-rate lookup by rate_id).","identity_key":"code","row_count":null,"last_updated":"2026-06-15","freshness_sla":"Rebuilt when fact_rate refreshes for a payer.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Serving mart: rebuilt when fact_rate refreshes for a payer — cadence follows the upstream commercial source, not a fixed clock."]},"raw_queryable_via":"Tools: compute_median_rate (code, state, payer) / explain_rate (rate_id); Athena: vlada_curated.mart_rate_by_code (partition-filter payer_id, state, code_prefix)","commercial_terms":"Derived from public TiC; redistributable.","provenance_chain_ref":"dim_substrate_mrf_version[substrate=commercial]","context_doc_path":"docs/context_library/commercial/mart_rate_by_code.md","known_gaps":["Coverage tracks fact_rate — current commercial truth packet v5 has 30/46 configured payer/network profiles indexed/live: amerihealth_caritas, amerihealth_nj, bcbs_id, bcbs_sc, carefirst, centene, cigna, emblemhealth, excellus, fallon, geisinger, health_new_england, health_partners, highmark, johns_hopkins_hc, kaiser, la_care, mclaren_health_plan, medical_mutual, molina, mvp, premera, priority_health, priority_health_via_cigna, quartz, sentara_health_plans, summacare, the_health_plan, tufts, and wellmark.","Live mart omits provider_npis/provider_count/source_files (builders project fact_rate scalar columns only; NPI-level lineage lives in the resolution engine). explain_rate/compute_median_rate read those fields and get empty defaults — use the resolution engine for NPI-level work.","quality_flags.is_ghost_candidate is hardcoded False in the Spark builder; the ghost gate is applied at the resolution-engine query layer, not materialized here.","Row count undocumented at table grain (one row per fact_rate row); Fallon parity measured at ~140.4M rows for a single payer-version."],"notes":"Canonical builder is the Spark port (pipelines/spark/commercial/build_mart_rate_by_code.py via EMR Serverless); the DuckDB builder under pipelines/curated/gold is DEPRECATED 2026-04-24. NEVER aggregate across modifier groups — see fact_rate gotchas.","tools":["compute_median_rate","explain_rate"]},{"source_id":"commercial_idx_rate_lookup","source_fqn":"vlada_curated.idx_rate_lookup","title":"Canonical-graph rate lookup index","domain":"commercial","stage":"index","status":"partial","grain":"Inverted index keyed by rate identity; traversed via idx_npi_provider_group (NPI entry) or idx_tin_provider_group (EIN entry, tin_type='ein' slice only) -> idx_pg_set_provider_group.","description":"Inverted index in the canonical-graph resolution engine. The resolution engine traverses it instead of materializing payer-wide rate x NPI edges. idx_tin_provider_group (2026-07-05 TIN identity engine Phase 1) adds the EIN entry point, one row per (source_file, pg_id, tin_value) with tin_scope_class fanout metadata and tin_index_path provenance ('membership' | 'bridge' -- bridge rows are npi-link-capped whole-system groups, system-shared evidence with lower-bound fanout).","identity_key":"rate_id","row_count":null,"last_updated":"2026-06-15","freshness_sla":"Rebuilt with the canonical graph per payer version.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Canonical-graph index: rebuilt per payer version with the graph — cadence follows the upstream commercial source."]},"raw_queryable_via":"Internal — reached via services/api/resolution_engine.py, not direct SQL.","commercial_terms":"Internal index over public TiC.","provenance_chain_ref":"docs/architecture/2026-04-29-canonical-graph-resolution-engine.md","context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["idx_rate_lookup lacks modifiers — rate-component split lives on fact_rate."],"notes":"No array<npi>; no LATERAL VIEW explode (flat-schema canonical-primitives lock).","tools":["benchmark_code","compare_rates","get_negotiated_rate","get_rate_with_provenance","lookup_rates_for_npi","lookup_rates_for_tin"]},{"source_id":"commercial_dim_payer","source_fqn":"vlada_curated.dim_payer","title":"Payer dimension + carrier hierarchy","domain":"commercial","stage":"dim","status":"live","grain":"One row per canonical payer_id.","description":"Canonical payer slugs, human names, and carrier ownership hierarchy (e.g. Cigna Healthspring under Cigna). Resolves free-text payer names.","identity_key":"payer_id","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Updated when a new payer is onboarded.","recollection":{"cadence":"event_driven","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Reference dimension: updated only when a new payer is onboarded — no fixed cadence."]},"raw_queryable_via":"Athena: vlada_curated.dim_payer","commercial_terms":"Internal reference dimension.","provenance_chain_ref":"Bundled FY2026 serving CSV plus additive source-truth Iceberg table medicare_silver.fact_ipps_wage_index_source_truth. FY2026 official CMS Table 2 is loaded/proven in source-truth with URL/SHA lineage; FY2008-FY2026 source artifacts are URL/SHA/dry-run proven but historical replay and serving migration remain gated.","context_doc_path":"docs/context_library/commercial/fact_rate.md","known_gaps":["Some plans are sub-payers of a parent; rental networks reference another carrier's contracts."],"notes":null,"tools":[]},{"source_id":"commercial_tic_raw","source_fqn":"s3://vlada-platform-raw/commercial_v2","title":"Raw TiC machine-readable files (bronze)","domain":"commercial","stage":"raw","status":"partial","grain":"One object per (payer, version, reporting period) raw MRF file.","description":"Archived raw bytes of payer TiC in-network-rate files (Best Evidence Rule). Partitioned payer=<payer>/version=<version>/.","identity_key":"source_file_id","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Fetched on the payer publish cadence (monthly).","recollection":{"cadence":"monthly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Raw object vintage is tracked via dim_substrate_mrf_version.content_sha256 + the version= S3 partition, not a queryable column; URLs expire in hours-days so fetch is a race."]},"raw_queryable_via":"S3 prefix s3://vlada-platform-raw/commercial_v2/ (object store; not row-queryable).","commercial_terms":"Public files archived for provenance/replay.","provenance_chain_ref":"dim_substrate_mrf_version[substrate=commercial].raw_s3_key","context_doc_path":"docs/context_library/commercial/fact_rate.md","known_gaps":["URLs expire in hours-days; extraction is a race."],"notes":"364K files tracked across ~54 payers configured.","tools":[]},{"source_id":"hospital_fact_chargemaster","source_fqn":"vlada_curated.fact_hospital_chargemaster","title":"Hospital chargemaster + payer-specific rates (HPT)","domain":"hospital","stage":"curated","status":"live","grain":"One row per (CCN, payer_name, plan, code, code_type, methodology, charge_type) at the file snapshot.","description":"Cleaned hospital prices extracted from CMS Hospital Price Transparency machine-readable files. Gross / cash / min / max / payer_specific + v3.0 allowed-amount percentile charge types.","identity_key":"hospital_ccn","row_count":4350000000,"last_updated":"2026-05-28","freshness_sla":"Hospitals republish at least annually (CMS); many quarterly.","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Cadence is a CMS floor (republish at least annually); many hospitals refresh quarterly, so 'annual' is a lower bound, not a guarantee. Per-file vintage is tracked via dim_mrf_version (mrf_version_id)."]},"raw_queryable_via":"Tool: get_hospital_chargemaster (ccn, code, charge_type); Athena: vlada_curated.fact_hospital_chargemaster","commercial_terms":"Public HPT files; redistributable as cleaned substrate.","provenance_chain_ref":"dim_mrf_version (schema/migrations/027_dim_mrf_version.sql); FA-6 unify into dim_substrate_mrf_version pending.","context_doc_path":"docs/context_library/hospital/fact_hospital_chargemaster.md","known_gaps":["~33% of US hospitals not yet covered (anti-bot, dead URLs, no-URL, in-discovery).","payer_name is free text, not canonical — join payers via mart_unified_pricing.","methodology determines what rate_value means; never compare across methodologies."],"notes":"4,151 CCNs live as of 2026-05-28 (~two-thirds of US hospitals); v3.0 enforced 2026-04-01.","tools":["care_site_price","county_expert","get_hospital_chargemaster","plan_hospital_price","prove_hospital_price","replay_hospital_price","state_agent","state_expert"]},{"source_id":"provider_facility_xref","source_fqn":"vlada_curated.provider_facility_xref","title":"CCN <-> NPI facility bridge","domain":"provider_identity","stage":"curated","status":"live","grain":"One row per (hospital_ccn, npi) candidate match with confidence + method.","description":"Confidence-scored bridge between hospital CCNs and provider NPIs. The join key for hospital x commercial unification. Floor for use is confidence >= 0.80.","identity_key":"hospital_ccn","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Rebuilt with hospital + NPPES refreshes.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Bridge: rebuilt with hospital + NPPES refreshes — cadence follows its upstreams."]},"raw_queryable_via":"Athena: vlada_curated.provider_facility_xref (filter confidence >= 0.80)","commercial_terms":"Derived from public NPPES + HPT.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["match_method fuzzy_name_zip is 0.7-1.0; slice fails if matched/expected < 0.50 for a CCN."],"notes":"match_method direct_facility_npi (1.0) or fuzzy_name_zip (RapidFuzz token_sort_ratio >= 70 + state + ZIP).","tools":[]},{"source_id":"hospital_hpt_raw","source_fqn":"s3://vlada-platform-raw/hospital","title":"Raw HPT machine-readable files (bronze)","domain":"hospital","stage":"raw","status":"live","grain":"One object per (CCN, version) raw HPT file.","description":"Archived raw bytes of hospital standard-charges files, partitioned ccn=<ccn>/version=<version>/.","identity_key":"hospital_ccn","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Re-discovered continuously via the URL discovery engine.","recollection":{"cadence":"continuous","watermark_field":"content_sha256","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'content_sha256' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Re-discovered continuously by the URL discovery engine; content_sha256 detects ping-only updates (last_updated flipped, bytes unchanged)."]},"raw_queryable_via":"S3 prefix s3://vlada-platform-raw/hospital/ (object store; not row-queryable).","commercial_terms":"Public files archived for provenance/replay.","provenance_chain_ref":"dim_mrf_version (schema/migrations/027_dim_mrf_version.sql)","context_doc_path":"docs/context_library/hospital/fact_hospital_chargemaster.md","known_gaps":["Ping-only updates (last_updated flipped, bytes unchanged) detected via content_sha256."],"notes":"Parsed by pipelines/streaming_hospital_parser.py.","tools":[]},{"source_id":"medicare_pfs","source_fqn":"medicare_silver.medicare_physician_fee_schedule","title":"Medicare Physician Fee Schedule (PFS)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, modifier, calendar_year) — CMS national PFS payment (non-facility + facility). CERTIFIED 2026-06-03.","description":"The universal benchmark denominator for the commercial-to-Medicare ratio (\"is this rate fair?\"). Use national_non_facility_payment (office) or national_facility_payment (facility). MATCH MODIFIER vs commercial (26 read / TC technical / global = NULL). National payment — there is NO locality column; join medicare_gpci_locality / medicare_zip_to_locality for a locality-adjusted rate.","identity_key":"hcpcs_code","row_count":92128,"last_updated":"2026-06-03","freshness_sla":"Annual (CMS publishes ~early November, effective Jan 1); mirror refreshed from RDS.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS publishes the next year in early November, effective Jan 1; conversion factor changes yearly."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_physician_fee_schedule — JOIN vlada_curated.fact_rate ON code=hcpcs_code, match modifier+calendar_year for the ratio.","commercial_terms":"Public CMS data.","provenance_chain_ref":"RDS->Iceberg mirror 2026-06-03 (ops/scripts/_fee_mirror_export.py + _fee_mirror_build.py); mirror_source + asserted_at on every row.","context_doc_path":"docs/context_library/medicare/pfs.md","known_gaps":["National payment only — no locality column; join GPCI/locality tables for a locality-adjusted rate.","GATE UPGRADED 2026-07-12: REPAIR EXECUTED — the 1,432 corrupted rows fixed in RDS in one guarded transaction, receipt run abf181c1f03947589f16fef3e79cef4c, per-key old-value predicates, in-transaction 4-value verification; mirror rebuilt via fee-mirror export+build; Athena 0115a917 proves 0 bad CF, 0 payment-recompute violations CY2022-25, counts unchanged; root cause was original ingest reading ENDO BASE instead of CONV FACTOR on endo-populated rows.","18,866 CY2026 rows lack the original CMS source_file_id; mirror lineage exists via mirror_source/asserted_at but source-file URL/SHA lineage is not queryable in Athena.","GATE UPGRADED 2026-07-12: DIRECT SOURCE-TRUTH LANE LIVE in medicare_silver.fact_pfs_rvu, built by pipelines/medicare/{silver/pfs_rvu_writer,ingest/pfs_rvu_runner}.py (commit 34fa3023b + hardening): 19-YEAR REPLAY EXECUTED with 584,448 rows / 35 vintages / 23 years CY2003-2025 complete; verification Athena b7847a8d proves 0 dup grains, 0 bad CF, 0 lineage nulls, CF single-valued per year matching CMS both ends (2003=36.7856, 2025=32.3465); rerun receipt IDEMPOTENT_SKIP.","GATE UPGRADED 2026-07-12: source-truth findings: CY2026 layout adds PRIC IND column and shifts ENDO/CONV right (same drift class; strict header allowlist caught it; 2026 remains behind the loud track-split gate and mirror serves it); rvu24b.zip contains no PPRRVU member (GPCI/ANES-only edition); 2015 bundle carries OCT + OCT05 correction members with correction-wins precedence pinned via manifest member field. Remaining gate items are 2026-era layout declaration + QPP sibling policy, serving projection + vintage-safe benchmark view swap (design dossier banked), MCP entitlement registration for fact_pfs_rvu, and 1998-2002 HCFA-era discovery (identified-source, hcfa.gov/stats/pufiles.htm — recoverable-vs-limit undecided).","Point-in-time mirror; do not historical-replay through the current RDS->Iceberg export+build until the source-mastery repair gate is accepted.","DMEPOS / Anesthesia / ESRD use separate schedules; lab = CLFS — a missing code is 'not PFS-priced', not $0."],"notes":"GATE UPGRADED 2026-07-12; source remains OPEN in gated_exact / wave_3_large_backfill with acceptance_gate_required=true. Repair and direct source-truth replay receipts are banked, but serving projection/view swap, 2026 layout/QPP policy, MCP entitlement, and CY1998-CY2002 HCFA-era discovery remain gate items. The old medicare_silver.dim_medicare_pfs name was never built; no get_medicare_rate tool exists — write the SQL.","tools":[]},{"source_id":"medicare_opps","source_fqn":"medicare_silver.medicare_opps_rates","title":"Medicare OPPS (hospital outpatient)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, calendar_year, quarter) — CMS OPPS APC payment_rate. CERTIFIED 2026-06-03.","description":"Outpatient Prospective Payment System rates — the hospital OUTPATIENT FACILITY benchmark (payment_rate). NOT PFS (benchmarking a facility charge against PFS is the #1 methodology error). EXCLUDE status_indicator G/K (pass-through drugs/biologicals; payment_rate up to ~$3.7M/unit for gene/cell therapies — real drug prices, not facility fees) and packaged status-N $0 rows from a facility-fee distribution.","identity_key":"hcpcs_code","row_count":18613,"last_updated":"2026-06-03","freshness_sla":"Annual calendar-year with quarterly addenda; mirror refreshed from RDS.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_opps_rates — JOIN vlada_curated.fact_hospital_chargemaster ON billing_code=hcpcs_code (outpatient setting).","commercial_terms":"Public CMS data.","provenance_chain_ref":"RDS->Iceberg mirror 2026-06-03 (ops/scripts/_fee_mirror_*); mirror_source + asserted_at on every row.","context_doc_path":"docs/context_library/medicare/opps_and_ipps.md","known_gaps":["Compare only methodology-compatible hospital rows (fee_schedule / case_rate).","status_indicator G/K = pass-through drug/biological APCs (very high $/unit) — exclude from facility-fee ratios.","Point-in-time mirror; re-run the RDS->Iceberg export+build after each CMS OPPS update.","GATE UPGRADED 2026-07-12: DIRECT SOURCE-TRUTH LANE EXECUTED in medicare_silver.fact_opps_addendum_b from commits 103772412 + c8de53167 + 33f81eeb9: 1,290,799 rows / 84 vintages; all 84 loadable artifacts; 9 correction-wins superseded + 2 quarantined per manifest. Athena 05e521be proves zero duplicate grains and zero lineage nulls for both tables. Remaining gates: serving projection + vintage-safe benchmark view (design dossier banked), MCP entitlement registration, and CY2005-Q2 Table 2 + 072 unpinnable correction artifact quarantined/enumerated."],"notes":"GATE UPGRADED 2026-07-12; source remains OPEN in gated_exact / wave_3_large_backfill with acceptance_gate_required=true. Direct source-truth replay is banked in medicare_silver.fact_opps_addendum_b; the CY2025 Q2 mirror remains the untouched serving baseline. Remaining gates are serving projection + vintage-safe benchmark view, MCP entitlement, and CY2005-Q2 Table 2 + 072 artifact quarantine/enumeration. The old medicare_silver.dim_medicare_opps name was never built. Historical source manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/medicare_opps_resolved_cms_files.json.","tools":[]},{"source_id":"medicare_ipps","source_fqn":"drug_silver.dim_msdrg","title":"Medicare IPPS inpatient acuity (MS-DRG relative weights)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (ms_drg, effective_period_start/fiscal-year) — CMS IPPS Table 5 relative weight + LOS. CERTIFIED 2026-06-03.","description":"The Medicare INPATIENT acuity benchmark — MS-DRG relative weight (weight_after_cap = final applied weight) + geometric/arithmetic LOS. RELATIVE weight only; an ABSOLUTE IPPS dollar payment is NOT computable (the IPPS base operating rate + hospital wage index are NOT loaded). Match hospital inpatient charges on MS-DRG, present relative acuity — do NOT quote an absolute Medicare inpatient payment. Physically in drug_silver (M-2 envelope sharing) but it is the Medicare inpatient benchmark.","identity_key":"ms_drg","row_count":764,"last_updated":"2026-06-03","freshness_sla":"Annual (federal fiscal year, Oct 1 start).","recollection":{"cadence":"annual","watermark_field":"effective_period_start","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'effective_period_start' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Federal fiscal year (not calendar year)."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_msdrg — match fact_hospital_chargemaster.billing_code=ms_drg (inpatient, code_type MS-DRG).","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/opps_and_ipps.md","known_gaps":["RELATIVE weight only — absolute IPPS dollars blocked (base rate + wage index NOT loaded).","IPPS pays per ADMISSION (whole DRG), not per code/line; itemized inpatient charges sum to far more by design.","Federal fiscal year (Oct 1), not calendar year — align the hospital file year to the IPPS fiscal year."],"notes":"CERTIFIED through the Source Acceptance Gate (product1-cert-msdrg-v1; DRG 470 weight 1.9289). The old medicare_silver.dim_medicare_ipps name was never built.","tools":[]},{"source_id":"medicare_asc","source_fqn":"medicare_silver.medicare_asc_rates","title":"Medicare ASC (Ambulatory Surgery Center) rates","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, calendar_year) — Medicare ASC payment_rate. CERTIFIED 2026-06-03.","description":"Medicare Ambulatory Surgery Center payment schedule (payment_rate) — the benchmark for ASC-setting surgery, a SEPARATE sibling system from OPPS. Don't substitute ASC for hospital-outpatient OPPS or vice-versa.","identity_key":"hcpcs_code","row_count":6642,"last_updated":"2026-06-03","freshness_sla":"Annual (effective Jan 1); mirror refreshed from RDS.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_asc_rates","commercial_terms":"Public CMS data.","provenance_chain_ref":"RDS->Iceberg mirror 2026-06-03 (ops/scripts/_fee_mirror_*); mirror_source + asserted_at on every row.","context_doc_path":"docs/context_library/medicare/opps_and_ipps.md","known_gaps":["Separate sibling system from OPPS — for ambulatory surgery centers, not hospital outpatient departments.","payment_indicator governs how the rate is set; don't compare across indicators blindly.","Point-in-time mirror; re-run the RDS->Iceberg export+build after each CMS ASC update.","GATE UPGRADED 2026-07-12: DIRECT SOURCE-TRUTH LANE EXECUTED in medicare_silver.fact_asc_addendum from commits 103772412 + c8de53167 + 33f81eeb9: 462,343 rows / 82 sheet-derived effective periods from 52 ZIPs; mirror tables untouched as serving baselines. Athena 05e521be proves zero duplicate grains and zero lineage nulls for both tables. Remaining gates: serving projection + vintage-safe benchmark view (design dossier banked), MCP entitlement registration, and CY2005-Q2 Table 2 + 072 unpinnable correction artifact quarantined/enumerated."],"notes":"GATE UPGRADED 2026-07-12; source remains OPEN in gated_exact / wave_3_large_backfill with acceptance_gate_required=true. Direct source-truth replay is banked in medicare_silver.fact_asc_addendum; the mirror table remains the untouched serving baseline. Remaining gates are serving projection + vintage-safe benchmark view, MCP entitlement, and CY2005-Q2 Table 2 + 072 artifact quarantine/enumeration. Historical source manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/medicare_asc_resolved_cms_files.json.","tools":[]},{"source_id":"medicare_clfs","source_fqn":"medicare_silver.medicare_clfs_rates","title":"Medicare CLFS (Clinical Laboratory Fee Schedule)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, modifier, indicator, calendar_year, quarter) — CLFS national_limit_amount. Source Truth repaired 2026-07-02.","description":"Medicare Clinical Laboratory Fee Schedule — the benchmark for LAB tests (national_limit_amount). Use CLFS, NOT PFS, for lab HCPCS codes; labs are priced on this separate schedule.","identity_key":"hcpcs_code","row_count":61076,"last_updated":"2026-07-02","freshness_sla":"Annual with quarterly addenda; refresh after each CMS CLFS release.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): modern national table medicare_silver.medicare_clfs_rates; accepted legacy locality leg medicare_silver.medicare_clfs_locality_rates.","commercial_terms":"Public CMS data.","provenance_chain_ref":"Official CMS CLFS ZIP files -> ops/scripts/medicare_clfs_official_backfill.py -> Iceberg; source_zip_url + source_zip_sha256 + source_csv_member + release_label + asserted_at on rows. 20CLABQ2 recovered from CMS sitemap URL 20clabq2-updated-462020.zip.","context_doc_path":"docs/context_library/medicare/clfs.md","known_gaps":["national_limit_amount is the payment cap; floor_amount is the floor in legacy files, but floor_amount is not populated in the served modern national table.","Lab codes only (the separate schedule for codes not in PFS).","Modern row-oriented CLFS releases 2018-2026 Q3 are loaded, including recovered 20CLABQ2.","Legacy locality/carrier CLFS releases 2008-2017 are loaded in the separate accepted table medicare_silver.medicare_clfs_locality_rates; do not silently union with the modern national table.","2005-2007 legacy CLFS ZIPs remain unrecovered after current CMS page probes and quick Wayback CDX checks.","floor_amount, personal_in_home, and legacy source_file_id are empty in the served modern table; ZIP-level provenance is populated instead."],"notes":"CERTIFIED (product1-cert-clfs-v2); Source Truth repaired for modern row-oriented CLFS releases through 2026 Q3 including recovered 20CLABQ2. Accepted legacy locality leg loaded 2008-2017 into medicare_silver.medicare_clfs_locality_rates; 2005-2007 remain a residual source-recovery gate.","tools":[]},{"source_id":"medicare_ma_ratebook","source_fqn":"medicare_silver.ma_county_ratebook","title":"MA county ratebook — CMS plan payment rates by county","domain":"medicare","stage":"silver","status":"live","grain":"One row per (rate_year, county) — CMS MA county benchmark rates by quality-bonus tier. CERTIFIED 2026-06-03.","description":"The county BENCHMARK — what CMS pays an MA plan per member in a county, by the county's quality-bonus tier: rate_5pct_bonus / rate_3_5pct_bonus / rate_0pct_bonus, plus rate_esrd. The revenue-rate INPUT for the Wolfe MA model (actual payment ~= benchmark x member risk score x rebate share).","identity_key":"ssa_county_code","row_count":42200,"last_updated":"2026-07-11","freshness_sla":"Annual (CMS Rate Announcement, ~April for the following year).","recollection":{"cadence":"annual","watermark_field":"rate_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rate_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_county_ratebook","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Current/modern 2015-2027 ratebook era remains loaded and served unchanged: 42,200 rows, 13 hashes, and zero duplicate (rate_year, ssa_county_code) groups.","The 25 official 1990-2014 legacy ZIPs are byte-secured with zero misses, 1,825,217 total bytes, and SHA-256 pins under s3://vlada-platform-raw/medicare/bronze/ma_ratebook_archive/{year}/; the acquisition manifest is s3://vlada-platform-raw/medicare/bronze/ma_ratebook_archive/acquisition_manifest_2026-07-11.json.","Exact deferred gate: accept lossless era-specific schema and grain for 1990-2011 AAPCC/CHOICE/risk-rate and 2012-2014 six-Star data; decide separate legacy table versus reviewed mapping; resolve 2001/2004 split-period identity; prove legacy SSA county-code validity, duplicate natural keys at the accepted grain, per-member byte/SHA, dry-run, and idempotency before any load.","Hard consumer guard: legacy ratebook data must not flow into the three-tier MCP tool or the MA revenue model until the deferred semantics gate is accepted."],"notes":"CERTIFIED (product1-cert-ma-ratebook-v1). Current modern era remains served unchanged; legacy 1990-2014 bytes are secured in an exact deferred lane.","tools":[]},{"source_id":"medicare_ma_stars","source_fqn":"medicare_silver.stars_ratings_summary","title":"Medicare Advantage Star Ratings (summary)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, part, payment_year) on is_current — CMS Star ratings summary. CERTIFIED 2026-06-03.","description":"The contract's CMS Star rating (summary_star, 1.0-5.0). 4+ stars => a 5% benchmark bonus AND a higher rebate share — the single biggest swing in MA plan economics. Powers the Stars-trajectory analyses (Wolfe sell-side).","identity_key":"contract_id","row_count":29282,"last_updated":"2026-06-03","freshness_sla":"Annual (CMS publishes in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"payment_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'payment_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Published in October for the following plan year; measure set + weights change year over year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.stars_ratings_summary (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["summary_star NULL = not rated (new / too-low-enrollment contract) — exclude from rating analytics; null != 0 stars.","Filter is_current=true; `part` is C / D / overall — pick the right one.","Measure set + weights are reweighted by CMS year over year."],"notes":"CERTIFIED (product1-cert-ma-stars-v1). 14 payment years; summary_star range 1.5-5.0.","tools":[]},{"source_id":"medicare_ma_stars_measure","source_fqn":"medicare_silver.stars_ratings_measure","title":"MA Star Ratings — per-measure value + star","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, measure_id, rating_year) — the per-measure raw value plus earned 1-5 star.","description":"The measure-level layer beneath the summary star: each contract's value and star on each measure. Drives Stars-trajectory and measure-gap analysis (Wolfe sell-side).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.stars_ratings_measure (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["measure_id is a DISPLAY ALIAS — join across years via medicare_silver.dim_stars_measure_crosswalk / CMIT #, never the raw code.","Filter is_current=true; scope by rating_year.","Uncertified (the acceptance-gate cert covers stars_ratings_summary only); grain-governed."],"notes":"Grain-governed (medicare_ma_stars). Powers the bit-exact RY2015-2026 recompute.","tools":[]},{"source_id":"medicare_ma_stars_cutpoints","source_fqn":"medicare_silver.stars_cutpoints","title":"MA Star Ratings — measure cut points","domain":"medicare","stage":"silver","status":"live","grain":"One row per (measure_id, star_level, org_subtype, rating_year) — the CMS threshold converting a raw measure value into a star.","description":"The annual CMS cut points (thresholds) per measure, star-level and org-subtype. The inputs that turn a raw measure value into a star; consumed by the recompute.","identity_key":"measure_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.stars_cutpoints (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Org-subtype-specific (cut points differ by contract type).","Tukey outlier deletion applies from RY2024.","Uncertified; grain-governed."],"notes":"Grain-governed (medicare_ma_stars).","tools":[]},{"source_id":"medicare_ma_stars_cai","source_fqn":"medicare_silver.stars_cai","title":"MA Star Ratings — Categorical Adjustment Index","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, part, fac_category, rating_year) — CAI input (final adjustment category plus LIS/DE/disabled mix).","description":"The Categorical Adjustment Index that adjusts summary stars for low-income/disabled enrollment mix. Carries a Puerto-Rico-Only flag.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.stars_cai (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["PR-Only contracts handled via a flag (see CR-C audit).","CAI active from RY2017; absent earlier.","Uncertified; grain-governed."],"notes":"Grain-governed (medicare_ma_stars).","tools":[]},{"source_id":"medicare_ma_stars_contracts","source_fqn":"medicare_silver.stars_contracts","title":"MA Star Ratings — contract metadata","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, rating_year) — org type, parent org, marketing name, SNP flag.","description":"Contract-level Stars metadata (org type, parent org, marketing name). The join spine from a Star rating to the carrier/parent for sell-side rollups.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.stars_contracts (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["PR contracts are first-class H-prefix rows.","For carrier rollups prefer CPSC parent_org where a cross-source identity is needed.","Uncertified; grain-governed."],"notes":"Grain-governed (medicare_ma_stars).","tools":[]},{"source_id":"medicare_ma_stars_measure_dim","source_fqn":"medicare_silver.dim_stars_measures","title":"MA Star Ratings — measure dimension","domain":"medicare","stage":"silver","status":"live","grain":"One row per (measure_id, rating_year) — measure inventory plus CMIT #, canonical_name, weight, direction, data source, domain.","description":"The per-year measure dictionary. Stable identity is the CMIT #; the C0x/D0x measure_id is a per-year display alias.","identity_key":"measure_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_stars_measures (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Stable identity = cmit_number; measure_id is a per-year display alias.","RY2015-2023 carry NO cmit_number (name is the only stable key those years).","Weights change year over year (e.g. patient-experience 4 to 2 in RY2026)."],"notes":"Grain-governed (medicare_ma_stars); seed methodology_seed.yaml.","tools":[]},{"source_id":"medicare_ma_stars_methodology","source_fqn":"medicare_silver.dim_stars_methodology","title":"MA Star Ratings — methodology dimension","domain":"medicare","stage":"silver","status":"live","grain":"One row per rating_year — era flags (CAI active, Tukey active, hold-harmless-expanded), reward-factor formula, performance_year and payment_year, tech-notes sha.","description":"The year-by-year methodology record that drives the recompute and the AEP/payment-year mapping for the rating tables.","identity_key":"rating_year","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_stars_methodology (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["RY2021 reflects COVID hold-harmless (frozen 2020 HEDIS/CAHPS).","The AEP/payment-year offset for the rating tables lives here (performance_year/payment_year).","Uncertified; grain-governed."],"notes":"Grain-governed (medicare_ma_stars).","tools":[]},{"source_id":"medicare_ma_stars_measure_crosswalk","source_fqn":"medicare_silver.dim_stars_measure_crosswalk","title":"MA Star Ratings — cross-year measure crosswalk","domain":"medicare","stage":"silver","status":"partial","grain":"One row per cross-year measure-identity edge (from to); crosswalk_type identity/renamed/etc; confidence certain/derived_name.","description":"The map that lets a measure be trended across CMS renumbering (e.g. C27 to C30). 84 certain (CMS Attachment J, RY2024-2026) plus 385 offline-derived (RY2015-2024).","identity_key":"from_measure_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"Annual (CMS publishes Star Ratings in October for the following plan year).","recollection":{"cadence":"annual","watermark_field":"rating_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rating_year' is the source's documented vintage column (the published Star Ratings year).","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_stars_measure_crosswalk (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["status=partial: the 385 derived_name edges (RY2015-2024) are UNVERIFIED offline canonical-name joins, NOT CMS-certain — filter by confidence.","55 measures remain unlinked (new/retired/re-introduced) pending CMS Attachment J — see the worklist artifact.","Uncertified; grain-governed."],"notes":"Grain-governed; backfilled by product1_stars_crosswalk_backfill_v1; see the crosswalk end-to-end plan. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_general","source_fqn":"medicare_silver.hedis_general","title":"MA hedis general","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, year). Contract metadata: organization type, plan type, Part D offering, enrollment count, region. Coded columns (General-0010 through General-0087) carry CMS Stars-Ratings semantics documented in `MADictionary{YEAR}.","description":"One row per (contract, year). Contract metadata: organization type, plan type, Part D offering, enrollment count, region. Coded columns (General-0010 through General-0087) carry CMS Stars-Ratings semantics documented in `MADictionary{YEAR}.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_general","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_hos_frm","source_fqn":"medicare_silver.hedis_hos_frm","title":"MA hedis hos frm","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, year). Health Outcomes Survey: Falls Risk Management. Two rates: (rate1) Talking with Doctor about Falling or Balance Problems, (rate2) Receiving Fall Risk Reduction Recommendation. ~600 rows per year.","description":"One row per (contract, year). Health Outcomes Survey: Falls Risk Management. Two rates: (rate1) Talking with Doctor about Falling or Balance Problems, (rate2) Receiving Fall Risk Reduction Recommendation. ~600 rows per year.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_frm","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_hos_mui","source_fqn":"medicare_silver.hedis_hos_mui","title":"MA hedis hos mui","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, year). HOS Management of Urinary Incontinence. Three rates (rate1, rate2, rate3). Published 2021+ only.","description":"One row per (contract, year). HOS Management of Urinary Incontinence. Three rates (rate1, rate2, rate3). Published 2021+ only.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_mui","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_hos_oto","source_fqn":"medicare_silver.hedis_hos_oto","title":"MA hedis hos oto","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, year). 3-column HOS sheet. Single rate column. Published 2019 and 2021 only; absent 2022+ (CMS appears to have renamed/retired in favor of hedishos_mui).","description":"One row per (contract, year). 3-column HOS sheet. Single rate column. Published 2019 and 2021 only; absent 2022+ (CMS appears to have renamed/retired in favor of hedishos_mui).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_oto","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_hos_pao","source_fqn":"medicare_silver.hedis_hos_pao","title":"MA hedis hos pao","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, year). 4-column HOS sheet. Two rates (rate1, rate2). Stable across 2019-2025 (excluding 2020 gap).","description":"One row per (contract, year). 4-column HOS sheet. Two rates (rate1, rate2). Stable across 2019-2025 (excluding 2020 gap).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_pao","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical PUF packages (1997-2018) / 108,579,442 bytes / zero misses at s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/ under acquisition_manifest_2026-07-12.json. Legacy replay is semantically gated; 2020 is an upstream non-publication.","tools":[]},{"source_id":"medicare_hedis_measures","source_fqn":"medicare_silver.hedis_measures","title":"MA hedis measures","domain":"medicare","stage":"silver","status":"live","grain":"Tall format: one row per (contract, HEDIS measure, indicator key, year). Reported rate plus confidence bounds (LCL/UCL), eligible population (2022+), denominator, numerator, member count (2022+). This is the Stars Ratings spine — every meas","description":"Tall format: one row per (contract, HEDIS measure, indicator key, year). Reported rate plus confidence bounds (LCL/UCL), eligible population (2022+), denominator, numerator, member count (2022+). This is the Stars Ratings spine — every meas","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_measures","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_national_rates","source_fqn":"medicare_silver.hedis_national_rates","title":"MA hedis national rates","domain":"medicare","stage":"silver","status":"live","grain":"CMS-published national weighted-average rate per (measure_code, indicator_key) per year. ~70-85 rows per year. The denominator for computing relative contract performance (Stars Ratings inputs).","description":"CMS-published national weighted-average rate per (measure_code, indicator_key) per year. ~70-85 rows per year. The denominator for computing relative contract performance (Stars Ratings inputs).","identity_key":"measure_code","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_national_rates","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_rau_measures","source_fqn":"medicare_silver.hedis_rau_measures","title":"MA hedis rau measures","domain":"medicare","stage":"silver","status":"live","grain":"Tall format: one row per (contract, RAU measure, indicator, year). Reports observed vs expected counts (with variance) for risk- adjusted utilization measures (admissions, ED visits, etc.). Added to MA-HEDIS PUFs starting in 2021. Per-row c","description":"Tall format: one row per (contract, RAU measure, indicator, year). Reports observed vs expected counts (with variance) for risk- adjusted utilization measures (admissions, ED visits, etc.). Added to MA-HEDIS PUFs starting in 2021. Per-row c","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_rau_measures","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual. Byte-secured deferred lane: all 22 historical MA HEDIS PUF packages (1997-2018) / 108,579,442 bytes / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_hedis_archive/; legacy semantic mapping and replay-safety gates remain.","tools":[]},{"source_id":"medicare_hedis_service_area","source_fqn":"medicare_silver.hedis_service_area","title":"MA hedis service area","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, county) per year. Long-format service area: contract operates in this county for this measurement year. Partial- county flag (SA-0070) indicates plans that cover only part of the county.","description":"One row per (contract, county) per year. Long-format service area: contract operates in this county for this measurement year. Partial- county flag (SA-0070) indicates plans that cover only part of the county.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","HEDIS is annual; 2020 is a real upstream gap."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_service_area","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2019 → present (2020 MISSING — CMS COVID skip).","2020 entirely missing upstream (CMS COVID skip); column drift 2019-2021 -> 2022+.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","tools":[]},{"source_id":"medicare_ma_contract_service_area","source_fqn":"medicare_silver.ma_contract_service_area","title":"MA ma contract service area","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, county) per month. Each row records the contract's organizational metadata (organization_name, plan_type, EGHP flag) plus the partial-county flag (TRUE when the contract covers only part of the county, per CMS's pu","description":"One row per (contract_id, county) per month. Each row records the contract's organizational metadata (organization_name, plan_type, EGHP flag) plus the partial-county flag (TRUE when the contract covers only part of the county, per CMS's pu","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_month","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_month' is the source's documented vintage column.","Standard CMS refresh cadence."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_contract_service_area","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2006-10 → 2026-04.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_contract_service_area.","tools":[]},{"source_id":"medicare_ma_state_county_penetration","source_fqn":"medicare_silver.ma_state_county_penetration","title":"MA ma state county penetration","domain":"medicare","stage":"silver","status":"live","grain":"One row per (county, month). Each row records eligibles (Medicare-eligible population), enrolled (MA-enrolled population), and penetration (enrolled / eligibles). Includes both FIPS-based and SSA-based county identifiers, plus human-readabl","description":"One row per (county, month). Each row records eligibles (Medicare-eligible population), enrolled (MA-enrolled population), and penetration (enrolled / eligibles). Includes both FIPS-based and SSA-based county identifiers, plus human-readabl","identity_key":"fipsst","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_month","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_month' is the source's documented vintage column.","Penetration monthly; suppression preserves bounds, NULL != 0."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_state_county_penetration","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2008-06 → 2026-04 (monthly).","Small-cell suppression: enrolled NULL but bounds [0,10] (NULL != 0); ~68 rows >100% are real CMS quirks.","Uncertified; deep-card grain-verified."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_state_county_penetration.","tools":[]},{"source_id":"medicare_mpf_benefit_summary_annual","source_fqn":"medicare_silver.mpf_benefit_summary_annual","title":"MA mpf benefit summary annual","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, plan, segment, year, service category, service). Cost_share is human-readable (e.g. \"$25 copay\", \"20% coinsurance\", \"$0 copay\", \"Not covered\"). Includes Original Medicare baseline rows for FFS comparison. Categories f","description":"One row per (contract, plan, segment, year, service category, service). Cost_share is human-readable (e.g. \"$25 copay\", \"20% coinsurance\", \"$0 copay\", \"Not covered\"). Includes Original Medicare baseline rows for FFS comparison. Categories f","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"contract_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'contract_year' is the source's documented vintage column.","MPF is the consumer crosswalk; reconcile, don't substitute."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mpf_benefit_summary_annual","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2020 → present (annual).","Consumer Plan Finder summary (2020+); use to RECONCILE PBP, not as PBP source of truth.","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family mpf_benefit_summary_report.","tools":[]},{"source_id":"medicare_pbp_changelog","source_fqn":"medicare_silver.pbp_changelog","title":"MA pbp changelog","domain":"medicare","stage":"silver","status":"partial","grain":"Parsed Readme_PBP_Benefits_YYYY.txt. Categories: column_length_change / variable_added / variable_removed / file_added / file_removed / policy_note / txt_sas_pairing / file_description / description. 2001-era Readmes have only description +","description":"Parsed Readme_PBP_Benefits_YYYY.txt. Categories: column_length_change / variable_added / variable_removed / file_added / file_removed / policy_note / txt_sas_pairing / file_description / description. 2001-era Readmes have only description +","identity_key":"report_year","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_changelog","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_field_dictionary","source_fqn":"medicare_silver.pbp_field_dictionary","title":"MA pbp field dictionary","domain":"medicare","stage":"silver","status":"partial","grain":"Parsed PBP{YEAR}_dictionary.xls/xlsx. 26K rows / year mapping (file, field) → (type, length, service category, codes). Substrate-as-self-documenting layer.","description":"Parsed PBP{YEAR}_dictionary.xls/xlsx. 26K rows / year mapping (file, field) → (type, length, service category, codes). Substrate-as-self-documenting layer.","identity_key":"report_year","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_field_dictionary","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_mrx","source_fqn":"medicare_silver.pbp_mrx","title":"MA pbp mrx","domain":"medicare","stage":"silver","status":"partial","grain":"Part D Rx plan-grain (mrx.txt). 2010+. Insulin / IRA fields added 2026.","description":"Part D Rx plan-grain (mrx.txt). 2010+. Insulin / IRA fields added 2026.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_mrx","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_mrx_gap_coverage","source_fqn":"medicare_silver.pbp_mrx_gap_coverage","title":"MA pbp mrx gap coverage","domain":"medicare","stage":"silver","status":"partial","grain":"Part D coverage-gap detail. Folded into pbp_mrx in 2026. Coverage: 2006-2025.","description":"Part D coverage-gap detail. Folded into pbp_mrx in 2026. Coverage: 2006-2025.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_mrx_gap_coverage","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_mrx_p","source_fqn":"medicare_silver.pbp_mrx_p","title":"MA pbp mrx p","domain":"medicare","stage":"silver","status":"partial","grain":"Part D plan × pharmacy-tier formulary detail. ~27K rows/yr. Coverage: 2006-present.","description":"Part D plan × pharmacy-tier formulary detail. ~27K rows/yr. Coverage: 2006-present.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_mrx_p","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_mrx_tier","source_fqn":"medicare_silver.pbp_mrx_tier","title":"MA pbp mrx tier","domain":"medicare","stage":"silver","status":"partial","grain":"Part D Rx tier-grain (mrx_tier.txt). Plan × tier. 2010+.","description":"Part D Rx tier-grain (mrx_tier.txt). Plan × tier. 2010+.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_mrx_tier","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_plan_area","source_fqn":"medicare_silver.pbp_plan_area","title":"MA pbp plan area","domain":"medicare","stage":"silver","status":"partial","grain":"Plan × county service area. ~2.3M rows per modern year. PlanArea + PlanRegionArea consolidated via area_type enum.","description":"Plan × county service area. ~2.3M rows per modern year. PlanArea + PlanRegionArea consolidated via area_type enum.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_plan_area","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_plan_region_area","source_fqn":"medicare_silver.pbp_plan_region_area","title":"MA pbp plan region area","domain":"medicare","stage":"silver","status":"partial","grain":"Regional-plan service area (parallel to plan_area for regional PPO). Coverage: 2006-present.","description":"Regional-plan service area (parallel to plan_area for regional PPO). Coverage: 2006-present.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_plan_region_area","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_sas_schema","source_fqn":"medicare_silver.pbp_sas_schema","title":"MA pbp sas schema","domain":"medicare","stage":"silver","status":"partial","grain":"SAS-parsed column manifest. One row per (table, year, column). Built from SAS files in the archive via sas_schema_parser primitive.","description":"SAS-parsed column manifest. One row per (table, year, column). Built from SAS files in the archive via sas_schema_parser primitive.","identity_key":"table_name","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_sas_schema","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_a","source_fqn":"medicare_silver.pbp_section_a","title":"MA pbp section a","domain":"medicare","stage":"silver","status":"partial","grain":"Plan universe. One row per (contract, plan, segment, version) per (year, quarter). Era-1 (pre-2010) rows synthesize segment_id='', version=0.","description":"Plan universe. One row per (contract, plan, segment, version) per (year, quarter). Era-1 (pre-2010) rows synthesize segment_id='', version=0.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_a","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b10_amb_trans","source_fqn":"medicare_silver.pbp_section_b10_amb_trans","title":"MA pbp section b10 amb trans","domain":"medicare","stage":"silver","status":"partial","grain":"Section B10: Ambulance / transport cost-share. Coverage: All years.","description":"Section B10: Ambulance / transport cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b10_amb_trans","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b11_dme_prosth_orth_sup","source_fqn":"medicare_silver.pbp_section_b11_dme_prosth_orth_sup","title":"MA pbp section b11 dme prosth orth sup","domain":"medicare","stage":"silver","status":"partial","grain":"Section B11: Durable medical equipment, prosthetics, orthotics, supplies. Per-plan benefit detail (plaintiff use case).","description":"Section B11: Durable medical equipment, prosthetics, orthotics, supplies. Per-plan benefit detail (plaintiff use case).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b11_dme_prosth_orth_sup","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b12_renal_dialysis","source_fqn":"medicare_silver.pbp_section_b12_renal_dialysis","title":"MA pbp section b12 renal dialysis","domain":"medicare","stage":"silver","status":"partial","grain":"Section B12: Renal dialysis cost-share. Coverage: All years.","description":"Section B12: Renal dialysis cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b12_renal_dialysis","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b14_preventive","source_fqn":"medicare_silver.pbp_section_b14_preventive","title":"MA pbp section b14 preventive","domain":"medicare","stage":"silver","status":"partial","grain":"Section B14: Preventive services. Widest single section (190 cols in 2026).","description":"Section B14: Preventive services. Widest single section (190 cols in 2026).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b14_preventive","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b15_partb_rx_drugs","source_fqn":"medicare_silver.pbp_section_b15_partb_rx_drugs","title":"MA pbp section b15 partb rx drugs","domain":"medicare","stage":"silver","status":"partial","grain":"Section B15: Part B Rx drugs benefit detail. Drug-substrate join surface. Coverage: All years.","description":"Section B15: Part B Rx drugs benefit detail. Drug-substrate join surface. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b15_partb_rx_drugs","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b19_model_test","source_fqn":"medicare_silver.pbp_section_b19_model_test","title":"MA pbp section b19 model test","domain":"medicare","stage":"silver","status":"partial","grain":"Section B19: Model test slot. Net-new base file 2026 (was VBID-only pre-2026). Coverage: 2026-present.","description":"Section B19: Model test slot. Net-new base file 2026 (was VBID-only pre-2026). Coverage: 2026-present.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b19_model_test","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b1a_inpat_hosp","source_fqn":"medicare_silver.pbp_section_b1a_inpat_hosp","title":"MA pbp section b1a inpat hosp","domain":"medicare","stage":"silver","status":"partial","grain":"Section B1a: Inpatient hospital (acute) cost-share. Splits from b1b psych starting 2010. Coverage: All years.","description":"Section B1a: Inpatient hospital (acute) cost-share. Splits from b1b psych starting 2010. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b1a_inpat_hosp","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b1b_inpat_hosp_psych","source_fqn":"medicare_silver.pbp_section_b1b_inpat_hosp_psych","title":"MA pbp section b1b inpat hosp psych","domain":"medicare","stage":"silver","status":"partial","grain":"Section B1b: Inpatient hospital psych cost-share. Split from b1a in 2010. Coverage: 2010-present.","description":"Section B1b: Inpatient hospital psych cost-share. Split from b1a in 2010. Coverage: 2010-present.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b1b_inpat_hosp_psych","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b20","source_fqn":"medicare_silver.pbp_section_b20","title":"MA pbp section b20","domain":"medicare","stage":"silver","status":"partial","grain":"Section B20: Supplemental benefits — other / unclassified. Coverage: All years.","description":"Section B20: Supplemental benefits — other / unclassified. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b20","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b2_snf","source_fqn":"medicare_silver.pbp_section_b2_snf","title":"MA pbp section b2 snf","domain":"medicare","stage":"silver","status":"partial","grain":"Section B2: Skilled nursing facility cost-share. Coverage: All years.","description":"Section B2: Skilled nursing facility cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b2_snf","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b3_cardiac_rehab","source_fqn":"medicare_silver.pbp_section_b3_cardiac_rehab","title":"MA pbp section b3 cardiac rehab","domain":"medicare","stage":"silver","status":"partial","grain":"Section B3: Cardiac/pulmonary rehab cost-share. Renamed from CORF in 2020. Coverage: 2020-present.","description":"Section B3: Cardiac/pulmonary rehab cost-share. Renamed from CORF in 2020. Coverage: 2020-present.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b3_cardiac_rehab","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b3_corf","source_fqn":"medicare_silver.pbp_section_b3_corf","title":"MA pbp section b3 corf","domain":"medicare","stage":"silver","status":"partial","grain":"Section B3: Comprehensive Outpatient Rehab Facility (CORF) cost-share. Pre-2020; superseded by cardiac_rehab. Coverage: 2001-2019.","description":"Section B3: Comprehensive Outpatient Rehab Facility (CORF) cost-share. Pre-2020; superseded by cardiac_rehab. Coverage: 2001-2019.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b3_corf","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b4_emerg_urgent","source_fqn":"medicare_silver.pbp_section_b4_emerg_urgent","title":"MA pbp section b4 emerg urgent","domain":"medicare","stage":"silver","status":"partial","grain":"Section B4: Emergency / urgent care cost-share. Coverage: All years.","description":"Section B4: Emergency / urgent care cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b4_emerg_urgent","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b5_partial_hosp","source_fqn":"medicare_silver.pbp_section_b5_partial_hosp","title":"MA pbp section b5 partial hosp","domain":"medicare","stage":"silver","status":"partial","grain":"Section B5: Partial hospitalization cost-share. Coverage: All years.","description":"Section B5: Partial hospitalization cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b5_partial_hosp","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b6_home_health","source_fqn":"medicare_silver.pbp_section_b6_home_health","title":"MA pbp section b6 home health","domain":"medicare","stage":"silver","status":"partial","grain":"Section B6: Home health cost-share. Coverage: All years.","description":"Section B6: Home health cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b6_home_health","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b7_health_prof","source_fqn":"medicare_silver.pbp_section_b7_health_prof","title":"MA pbp section b7 health prof","domain":"medicare","stage":"silver","status":"partial","grain":"Section B7: Health professional services (PCP/specialist) cost-share. Wide schema. Coverage: All years.","description":"Section B7: Health professional services (PCP/specialist) cost-share. Wide schema. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b7_health_prof","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b8_clin_diag_ther","source_fqn":"medicare_silver.pbp_section_b8_clin_diag_ther","title":"MA pbp section b8 clin diag ther","domain":"medicare","stage":"silver","status":"partial","grain":"Section B8: Clinical/diagnostic/therapeutic services cost-share. Coverage: All years.","description":"Section B8: Clinical/diagnostic/therapeutic services cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b8_clin_diag_ther","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_b9_outpat_hosp","source_fqn":"medicare_silver.pbp_section_b9_outpat_hosp","title":"MA pbp section b9 outpat hosp","domain":"medicare","stage":"silver","status":"partial","grain":"Section B9: Outpatient hospital cost-share. Coverage: All years.","description":"Section B9: Outpatient hospital cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_b9_outpat_hosp","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_c","source_fqn":"medicare_silver.pbp_section_c","title":"MA pbp section c","domain":"medicare","stage":"silver","status":"partial","grain":"Section C: Out-of-pocket maximums + optional supplemental benefits. 226 cols. Coverage: All years.","description":"Section C: Out-of-pocket maximums + optional supplemental benefits. 226 cols. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_c","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_c_oon","source_fqn":"medicare_silver.pbp_section_c_oon","title":"MA pbp section c oon","domain":"medicare","stage":"silver","status":"partial","grain":"Section C OON: Out-of-network cost-share detail. Coverage: All years (plans with OON only).","description":"Section C OON: Out-of-network cost-share detail. Coverage: All years (plans with OON only).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_c_oon","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_c_pos","source_fqn":"medicare_silver.pbp_section_c_pos","title":"MA pbp section c pos","domain":"medicare","stage":"silver","status":"partial","grain":"Section C POS: Point-of-service cost-share detail. Coverage: All years (plans with POS only).","description":"Section C POS: Point-of-service cost-share detail. Coverage: All years (plans with POS only).","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_c_pos","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_d","source_fqn":"medicare_silver.pbp_section_d","title":"MA pbp section d","domain":"medicare","stage":"silver","status":"partial","grain":"Section D: Part D plan-level benefit detail. 463 cols (widest single file). Pharma use case.","description":"Section D: Part D plan-level benefit detail. 463 cols (widest single file). Pharma use case.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_d","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_d_oon","source_fqn":"medicare_silver.pbp_section_d_oon","title":"MA pbp section d oon","domain":"medicare","stage":"silver","status":"partial","grain":"Section D OON: Part D out-of-network cost-share. Coverage: All years.","description":"Section D OON: Part D out-of-network cost-share. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_d_oon","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_section_d_opt","source_fqn":"medicare_silver.pbp_section_d_opt","title":"MA pbp section d opt","domain":"medicare","stage":"silver","status":"partial","grain":"Section D opt: Part D optional supplemental drug benefits. Pre-2022 used `opts` spelling. Coverage: All years.","description":"Section D opt: Part D optional supplemental drug benefits. Pre-2022 used `opts` spelling. Coverage: All years.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_section_d_opt","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","Null numeric benefit amount is NOT $0 — apply docs/skills/pbp-semantics/SKILL.md.","Raw PBP is CMS-software-coded (era shifts, skip logic); for analysis prefer the cleaned vw_pbp_* views.","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_pbp_vbid_overlay","source_fqn":"medicare_silver.pbp_vbid_overlay","title":"MA pbp vbid overlay","domain":"medicare","stage":"silver","status":"partial","grain":"Union of 21-24 VBID overlay files. vbid_variant enum: {uf, ssbci, b19a_uf, b19a_ssbci, b19b_uf, b19b_ssbci, plain, discontinued_retained}. parent_section links to Section B (b13, b14, etc.). VBID introduced 2017; retained blanked 2026+.","description":"Union of 21-24 VBID overlay files. vbid_variant enum: {uf, ssbci, b19a_uf, b19a_ssbci, b19b_uf, b19b_ssbci, plain, discontinued_retained}. parent_section links to Section B (b13, b14, etc.). VBID introduced 2017; retained blanked 2026+.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column.","PBP metadata/overlay; refresh-cadence only."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.pbp_vbid_overlay","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["Coverage: 2001 → present (annual pre-2018 & 2025+; quarterly 2018-2024).","PBP metadata/overlay table (not a benefit-amount fact).","Row count unpinned."],"notes":"Grain-governed; live in Glue / query_substrate. Source family pbp_benefits.","tools":[]},{"source_id":"medicare_snp_data","source_fqn":"medicare_silver.snp_data","title":"MA snp data","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, plan, segment) per month. Each row records plan enrollment count, plan_type (HMO/HMOPOS/PPO/PFFS/etc.), the SNP category (Chronic/Dual/Institutional), and for chronic-SNPs the specific specialty disease(s) the plan ta","description":"One row per (contract, plan, segment) per month. Each row records plan enrollment count, plan_type (HMO/HMOPOS/PPO/PFFS/etc.), the SNP category (Chronic/Dual/Institutional), and for chronic-SNPs the specific specialty disease(s) the plan ta","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"report_month","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_month' is the source's documented vintage column.","Standard CMS refresh cadence."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.snp_data","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Coverage: 2007-05 → 2026-04 (monthly).","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family snp_data.","tools":[]},{"source_id":"medicare_vw_pbp_b19_combined_package","source_fqn":"medicare_semantic.vw_pbp_b19_combined_package","title":"PBP b19 combined package (cleaned view)","domain":"medicare","stage":"semantic_view","status":"partial","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned b19 combined package benefit.","description":"Cleaned source-faithful PBP b19 combined package rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning su","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_b19_combined_package","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/b19_combined_package/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_cardiac_pulmonary_rehab","source_fqn":"medicare_semantic.vw_pbp_cardiac_pulmonary_rehab","title":"PBP cardiac pulmonary rehab (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned cardiac pulmonary rehab benefit.","description":"Cleaned source-faithful PBP cardiac pulmonary rehab rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_cardiac_pulmonary_rehab","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/cardiac_pulmonary_rehab/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_clinical_diagnostic_therapeutic","source_fqn":"medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic","title":"PBP clinical diagnostic therapeutic (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned clinical diagnostic therapeutic benefit.","description":"Cleaned source-faithful PBP clinical diagnostic therapeutic rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent r","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/clinical_diagnostic_therapeutic/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_dental","source_fqn":"medicare_semantic.vw_pbp_dental","title":"PBP dental (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned dental benefit.","description":"Cleaned source-faithful PBP dental rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for dent","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_dental","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/dental/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_dme","source_fqn":"medicare_semantic.vw_pbp_dme","title":"PBP dme (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned dme benefit.","description":"Cleaned source-faithful PBP dme rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for dme (vs","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_dme","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/dme/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_emergency_urgent","source_fqn":"medicare_semantic.vw_pbp_emergency_urgent","title":"PBP emergency urgent (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned emergency urgent benefit.","description":"Cleaned source-faithful PBP emergency urgent rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surfac","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_emergency_urgent","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/emergency_urgent/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_health_professionals","source_fqn":"medicare_semantic.vw_pbp_health_professionals","title":"PBP health professionals (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned health professionals benefit.","description":"Cleaned source-faithful PBP health professionals rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning su","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_health_professionals","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/health_professionals/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_hearing","source_fqn":"medicare_semantic.vw_pbp_hearing","title":"PBP hearing (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned hearing benefit.","description":"Cleaned source-faithful PBP hearing rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for hea","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_hearing","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/hearing/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_home_health","source_fqn":"medicare_semantic.vw_pbp_home_health","title":"PBP home health (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned home health benefit.","description":"Cleaned source-faithful PBP home health rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_home_health","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/home_health/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_inpatient_hospital","source_fqn":"medicare_semantic.vw_pbp_inpatient_hospital","title":"PBP inpatient hospital (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned inpatient hospital benefit.","description":"Cleaned source-faithful PBP inpatient hospital rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surf","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_inpatient_hospital","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/inpatient_hospital/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_inpatient_psychiatric","source_fqn":"medicare_semantic.vw_pbp_inpatient_psychiatric","title":"PBP inpatient psychiatric (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned inpatient psychiatric benefit.","description":"Cleaned source-faithful PBP inpatient psychiatric rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning s","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_inpatient_psychiatric","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/inpatient_psychiatric/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_moop","source_fqn":"medicare_semantic.vw_pbp_moop","title":"PBP moop (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned moop benefit.","description":"Cleaned source-faithful PBP moop rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for moop (","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_moop","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/moop/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_otc","source_fqn":"medicare_semantic.vw_pbp_otc","title":"PBP otc (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned otc benefit.","description":"Cleaned source-faithful PBP otc rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for otc (vs","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_otc","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/otc/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_outpatient_hospital","source_fqn":"medicare_semantic.vw_pbp_outpatient_hospital","title":"PBP outpatient hospital (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned outpatient hospital benefit.","description":"Cleaned source-faithful PBP outpatient hospital rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning sur","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_outpatient_hospital","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/outpatient_hospital/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_partb_rx_drugs","source_fqn":"medicare_semantic.vw_pbp_partb_rx_drugs","title":"PBP partb rx drugs (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned partb rx drugs benefit.","description":"Cleaned source-faithful PBP partb rx drugs rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_partb_rx_drugs","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/partb_rx_drugs/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_partd_drugs","source_fqn":"medicare_semantic.vw_pbp_partd_drugs","title":"PBP partd drugs (cleaned view)","domain":"medicare","stage":"semantic_view","status":"partial","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned partd drugs benefit.","description":"Cleaned source-faithful PBP partd drugs rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_partd_drugs","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/partd_drugs/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_partd_tier","source_fqn":"medicare_semantic.vw_pbp_partd_tier","title":"PBP partd tier (cleaned view)","domain":"medicare","stage":"semantic_view","status":"partial","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned partd tier benefit.","description":"Cleaned source-faithful PBP partd tier rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_partd_tier","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/partd_tier/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_partial_hospitalization","source_fqn":"medicare_semantic.vw_pbp_partial_hospitalization","title":"PBP partial hospitalization (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned partial hospitalization benefit.","description":"Cleaned source-faithful PBP partial hospitalization rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_partial_hospitalization","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/partial_hospitalization/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_preventive","source_fqn":"medicare_semantic.vw_pbp_preventive","title":"PBP preventive (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned preventive benefit.","description":"Cleaned source-faithful PBP preventive rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_preventive","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/preventive/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_renal_dialysis","source_fqn":"medicare_semantic.vw_pbp_renal_dialysis","title":"PBP renal dialysis (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned renal dialysis benefit.","description":"Cleaned source-faithful PBP renal dialysis rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_renal_dialysis","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/renal_dialysis/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_section_c_pos_oon","source_fqn":"medicare_semantic.vw_pbp_section_c_pos_oon","title":"PBP section c pos oon (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned section c pos oon benefit.","description":"Cleaned source-faithful PBP section c pos oon rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surfa","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_section_c_pos_oon","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/section_c_pos_oon/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_snf","source_fqn":"medicare_semantic.vw_pbp_snf","title":"PBP snf (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned snf benefit.","description":"Cleaned source-faithful PBP snf rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for snf (vs","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_snf","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/snf/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_supplemental_other","source_fqn":"medicare_semantic.vw_pbp_supplemental_other","title":"PBP supplemental other (cleaned view)","domain":"medicare","stage":"semantic_view","status":"partial","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned supplemental other benefit.","description":"Cleaned source-faithful PBP supplemental other rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surf","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_supplemental_other","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/supplemental_other/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_transportation","source_fqn":"medicare_semantic.vw_pbp_transportation","title":"PBP transportation (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned transportation benefit.","description":"Cleaned source-faithful PBP transportation rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_transportation","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/transportation/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_vw_pbp_vision","source_fqn":"medicare_semantic.vw_pbp_vision","title":"PBP vision (cleaned view)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (contract_id, plan_id, segment, plan_year) cleaned vision benefit.","description":"Cleaned source-faithful PBP vision rows: era-normalized, CMS codes decoded, with offered_status/numeric_amount_observability/null_amount_reason/annualization_policy/combined_limit_policy/confidence_tier. The agent reasoning surface for visi","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-06","freshness_sla":"CMS publication cadence; see coverage notes.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage column.","A null numeric benefit amount is NOT $0 (see docs/skills/pbp-semantics/SKILL.md); this recollection block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_pbp_vision","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Null numeric benefit amount is NEVER $0 (null_amount_reason explains why) — docs/skills/pbp-semantics/SKILL.md.","consumer_document_reconciliation_status defaults not_checked; source-faithful != consumer-verified.","CONDITIONAL: offline-validated; live values not yet certified."],"notes":"Cleaned PBP reasoning surface (categories/vision/contract.yaml); raw is pbp_section_*.","tools":[]},{"source_id":"medicare_pbp_benefits","source_fqn":"medicare_semantic.vw_pbp_benefits","title":"MA Plan Benefit Package (PBP) — semantic view","domain":"medicare","stage":"semantic_view","status":"partial","grain":"One row per (contract_id, plan_id, segment, benefit, plan_year).","description":"Semantic view over the CMS Plan Benefit Package files — cost-sharing, benefits, and supplemental-benefit detail per MA plan. Apply the pbp-semantics skill before benefit analysis.","identity_key":"plan_id","row_count":null,"last_updated":"2026-01-01","freshness_sla":"Annual (plan-year aligned), with monthly/quarterly companions.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Plan-year aligned, with monthly/quarterly companions. PBP semantics: a null numeric benefit amount is NOT $0 — see docs/skills/pbp-semantics/SKILL.md; this block governs refresh cadence only."]},"raw_queryable_via":"Athena: medicare_semantic.vw_pbp_benefits","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_source_registry_cache","context_doc_path":"docs/context_library/medicare/pfs.md","known_gaps":["PBP semantics are subtle; validate against Summary of Benefits PDFs (SB matcher)."],"notes":"25-view semantic layer; see docs/skills/pbp-semantics/SKILL.md.","tools":[]},{"source_id":"medicare_enrollment_monthly_county","source_fqn":"medicare_silver.enrollment_monthly_county","title":"MA/Part D enrollment — CPSC county grain","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, state_code, county_fips, month) enrollment count.","description":"CMS CPSC (Contract/Plan/State/County) monthly MA + Part D enrollment at county grain. The substrate behind get_enrollment_trend and the MA enrollment-trend proof rail. Includes EGHP (flagged); excludes Original Medicare (FFS). County cells with <=10 enrollees are CMS-suppressed (`*`) and carried as bounds [1,10] via enrollment_lower_bound/upper_bound + suppression_reason_code='redacted_small_cell'.","identity_key":"contract_id","row_count":null,"last_updated":"2026-05-11","freshness_sla":"Monthly (CMS CPSC release, ~15th of each month).","recollection":{"cadence":"monthly","watermark_field":"report_month","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_month' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Watermark column is named report_month on the Athena path and observed_period on the pyiceberg path (same grain, not reconciled in code); CPSC releases ~15th of each month."]},"raw_queryable_via":"Tool: get_enrollment_trend; Athena: medicare_silver.enrollment_monthly_county","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_source_registry_cache","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Month column referenced as observed_period (pyiceberg path) and report_month (Athena path); same grain, name not reconciled in code.","Publication gaps 2016-12 / 2021-06 / 2025-03 RESOLVED 2026-05-11 (corrected URLs ingested; see pipelines/medicare/data/gap_registry.yaml).","Pre/post-2018 grain pivot empirically falsified 2026-05-11; no era enforcement applied."],"notes":"County form of the catalogued aggregate medicare_silver.fact_ma_enrollment (source_id medicare_ma_enrollment). row_count null (a code comment cites ~612M rows, not catalog-measured).","tools":[]},{"source_id":"medicare_enrollment_monthly_plan","source_fqn":"medicare_silver.enrollment_monthly_plan","title":"MA/Part D enrollment — plan grain","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, month) plan-level enrollment count.","description":"CMS monthly MA + Part D enrollment at plan grain. Declared as the primary table of the MA enrollment-trend proof receipt and pinned to its silver_published snapshot.","identity_key":"contract_id","row_count":null,"last_updated":"2026-05-13","freshness_sla":"Monthly (CMS enrollment release).","recollection":{"cadence":"monthly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Declared for snapshot-pinning but not yet read by code (Phase 1 reads only the county table); watermark column not asserted beyond grain."]},"raw_queryable_via":"Tools: plan_ma_enrollment_trend_proof / prove_ma_enrollment_trend; Athena: medicare_silver.enrollment_monthly_plan","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_source_registry_cache","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Declared for snapshot-pinning by the proof rail; not yet read by code (Phase 1 scaffolding reads only enrollment_monthly_county). Phase 2 will swap to a direct silver read."],"notes":"status=partial: no columns are read in current code. Schema fields not asserted beyond grain (not evidenced in source).","tools":[]},{"source_id":"medicare_plan_crosswalks_annual","source_fqn":"medicare_silver.plan_crosswalks_annual","title":"MA plan crosswalk — annual lineage (silver)","domain":"medicare","stage":"silver","status":"partial","grain":"Annual plan-crosswalk lineage edges across contract-years.","description":"CMS annual plan-crosswalk lineage (consolidations, renames, terminations) used by the MA enrollment-trend proof rail to stitch enrollment across plan-year boundaries. Pinned to its silver_published snapshot in the proof receipt's lineage_table slot.","identity_key":"contract_id","row_count":null,"last_updated":"2026-05-13","freshness_sla":"Annual (with the enrollment cycle).","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Declared for snapshot-pinning; lineage resolution currently uses curated YAML registries, not this table — watermark column not asserted beyond grain."]},"raw_queryable_via":"Tools: plan_ma_enrollment_trend_proof / prove_ma_enrollment_trend; Athena: medicare_silver.plan_crosswalks_annual","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_source_registry_cache","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Declared for snapshot-pinning; not directly read in current code (lineage resolution uses curated YAML registries, not this table)."],"notes":"Annual-snapshot sibling of the catalogued medicare_silver.dim_plan_crosswalk (source_id medicare_plan_crosswalk). status=partial; schema not asserted beyond grain.","tools":[]},{"source_id":"medicare_monthly_contract_enrollment_summary","source_fqn":"medicare_silver.monthly_contract_enrollment_summary","title":"MA enrollment — monthly contract summary","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, report_month) — CMS Monthly Enrollment by Contract (member counts). CERTIFIED 2026-06-03.","description":"CMS \"Monthly Enrollment by Contract\" — member counts per MA/Part D contract per month (enrollment_count). The member-volume input for MA revenue (revenue ~= enrollment x county benchmark x risk x rebate share).","identity_key":"contract_id","row_count":198917,"last_updated":"2026-06-03","freshness_sla":"Monthly (CMS enrollment release); through 2026-04.","recollection":{"cadence":"monthly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Declared for snapshot-pinning; not directly read in current code (Phase 1 scaffolding) — watermark column not asserted beyond grain."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.monthly_contract_enrollment_summary","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["enrollment_count is NULL when CMS SUPPRESSED the cell (<11 members) — enrollment_lower/upper_bound carry the range. Null != 0 members.","CONTRACT-level; for PLAN-level use medicare_silver.enrollment_monthly_plan.","CARRIER ROLLUP: roll contract-level rows up to the parent/carrier on parent_org_raw, NEVER name-match organization_name (name-match badly undercounts: Humana via %HUMANA% = 37 contracts/$67.7B MLR, via parent_org_raw='Humana Inc.' = 48 contracts/$95.5B). parent_org_raw is the join key for rolling ANY contract-keyed MA source (mlr/payment/stars/hedis) up to the carrier.","parent_org_raw is TIME-VARYING (M&A/rebrands) — treat parent as AS-OF-DATE; pin a consistent report_month per year for a clean rollup."],"notes":"CERTIFIED (product1-cert-ma-enrollment-v1). 237 months through 2026-04; e.g. 2026-04 Humana 3.73M members.","tools":[]},{"source_id":"medicare_ma_mlr","source_fqn":"medicare_silver.ma_mlr","title":"MA / Part-D Medical Loss Ratio (MLR)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract_id, contract_year). CMS MA/Part-D Medical Loss Ratio Public Use File, 4,984 rows across 2014-2023. Contract-level (no plan grain).","description":"The contract-level efficiency / profitability lens: adjusted_mlr (share of revenue spent on care + quality improvement vs admin/profit), remittance_amount (owed to CMS for missing the 0.85 floor), and in detailed years total_revenue, total_claims, member_months, the MLR numerator/denominator, and an incurred-claims split by supplemental benefit. The P&L input for the investor MA-VAT.","identity_key":"contract_id","row_count":4984,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS MLR PUF release).","recollection":{"cadence":"annual","watermark_field":"contract_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'contract_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_mlr","commercial_terms":"Public CMS data.","provenance_chain_ref":"External CSV (OpenCSVSerde); trace_to_source via catalog_provenance_index.json.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["BIMODAL FORMAT: WIDE detail for 2014-2017 + 2023, NARROW (adjusted_mlr + remittance only) for 2018-2022. The MLR + remittance spine is populated EVERY year; detail columns are NULL for 2018-2022. Every row carries detail_available, so a NULL detail line is never $0.","All columns are string (OpenCSVSerde): cast numerics on read.","JOINS to ma_plan_payment_* / stars_ratings_summary / monthly_contract_enrollment_summary on (contract_id, year). Roll up to carrier via parent_org_raw on the enrollment summary, NOT a name-match. Layer-2 tool: get_mlr."],"notes":"New source captured end-to-end (PRs","tools":[]},{"source_id":"medicare_hospital_cost_report_overall","source_fqn":"medicare_silver.hospital_cost_report_overall","title":"Hospital cost report — whole-hospital cost-to-charge (HCRIS 2552-10)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (ccn, fiscal-year-end). CMS Medicare Hospital Cost Report (HCRIS, form 2552-10) Worksheet C. 81,368 report-years, 6,949 hospitals, FY2010-2024.","description":"The whole-hospital ACTUAL-COST lens: overall_ccr (cost-to-charge ratio = total_cost / total_charge from Worksheet C). Applied to a billed charge it estimates the real cost of care. This is the COST leg reference-based-pricing vendors (Imagine360/ELAP) price against; joined to our MRF negotiated rate + Medicare it completes the cost / rate / Medicare / fair-RBP-price picture that no one else holds. Use the DEPT table for service-specific cost, this for the hospital-wide ratio.","identity_key":"ccn","row_count":81368,"last_updated":"2026-06-15","freshness_sla":"Annual (CMS HCRIS HOSP10 quarterly snapshot; reports lag ~12-21 months).","recollection":{"cadence":"annual","watermark_field":"fy_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fy_year' is the report's fiscal-year-end vintage.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: HCRIS lags 12-21 months and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_overall","commercial_terms":"Public CMS data.","provenance_chain_ref":"External CSV (OpenCSVSerde) from HCRIS HOSP10FY{year}.zip Worksheet C000001; cell-exact, A/B/C ties validated per fiscal year.","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["CCR==1.0 SENTINEL: ~0.2% of hospitals (10 of 12 of them in New York, CCN prefix 33) file CHARGES AS COSTS (cost==charge), so overall_ccr pins to 1.000 across their entire history in fully-settled reports. est_cost = charge x 1.0 is NON-INFORMATIVE as a cost floor. The column charge_as_cost='true' flags these (|cost-charge|<1 or ccr>=0.99). EXCLUDE charge_as_cost='true' for any cost-floor analysis; it is NY-concentrated so it specifically contaminates Tri-State medians.","JOINS to our hospital MRF on ccn = hospital_ccn (vlada_curated.vw_fact_hospital_chargemaster_current); all 4,781 served hospitals match a cost report (100%).","CCR is a blunt average (~25-35% accurate at single-claim, reliable only aggregated to DRG/service level; Shwartz 1995). Use the DEPT grain for service-specific cost; overall_ccr overstates cost ~10x for low-CCR services like CT/MRI.","plausible=1 means 0.05<=overall_ccr<=2; rows outside that band (and charge_as_cost rows) should be screened. All columns are string (OpenCSVSerde): cast numerics on read.","rpt_status is the HCRIS settlement code; the highest rpt_rec_num per (ccn, fy_end) is the chosen version. FY2024 rows exist (a FY2023 file carries reports whose fiscal year ends in 2024)."],"notes":null,"tools":[]},{"source_id":"medicare_hospital_cost_report_dept","source_fqn":"medicare_silver.hospital_cost_report_dept","title":"Hospital cost report — department cost-to-charge (HCRIS 2552-10 Worksheet C)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (ccn, fiscal-year-end, cost_center_line). 1,474,951 rows, 6,887 hospitals, FY2011-2024, 553 distinct cost centers.","description":"The SERVICE-SPECIFIC actual-cost lens, and the load-bearing one: dept_ccr (cost-to-charge ratio for one Worksheet C cost center). CCR spreads ~17x across departments (CT ~0.04 vs Clinic ~0.64), so a per-code cost estimate MUST use the service's own cost center via the HCPCS->cost-center crosswalk, never the hospital overall ratio. cost_center_label names the standard 2552-10 lines (Operating Room=50, CT=57, MRI=58, Cardiac Cath=59, Laboratory=60, Clinic=90, Emergency=91).","identity_key":"ccn","row_count":1474951,"last_updated":"2026-06-15","freshness_sla":"Annual (CMS HCRIS HOSP10 quarterly snapshot; reports lag ~12-21 months).","recollection":{"cadence":"annual","watermark_field":"fy_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fy_year' is the report's fiscal-year-end vintage.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: HCRIS lags 12-21 months and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_dept","commercial_terms":"Public CMS data.","provenance_chain_ref":"External CSV (OpenCSVSerde) from HCRIS HOSP10FY{year}.zip Worksheet C000001 col 9; every dept_ccr validated == col1/col8 per fiscal year.","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["USE THE DEPARTMENT CCR, NEVER THE OVERALL. CCR varies ~17x across cost centers; using the overall or a wrong center overstates low-CCR service cost ~10x (the CT-vs-overall trap). Map a HCPCS/CPT to its cost_center_line via the crosswalk before applying dept_ccr.","cost_center_line is encoded as line x 100 (e.g. '05700'=line 57 CT, '09000'=line 90 Clinic, '05000'=line 50 OR); subscripted centers (e.g. '05701') roll under the parent line. cost_center_label is the human name.","CCR==1.0 SENTINEL same as the overall table: charge_as_cost='true' flags cost==charge non-informative filers (NY-concentrated). EXCLUDE them for cost-floor work.","E&M / professional-dominant codes (99xxx office visits -> Clinic center) carry a near-1.0 CCR because clinic cost is mostly professional labor with near-zero supply markup, so cost-plus floor ~= charge ~= rate and there is NO RBP arbitrage. The cost-plus lens applies to HIGH-MARKUP FACILITY services (imaging, surgery, lab); flag E&M as out-of-scope.","All columns are string (OpenCSVSerde): cast numerics on read. Joins to our MRF on ccn = hospital_ccn."],"notes":null,"tools":["fair_rbp_book","fair_rbp_price"]},{"source_id":"medicare_facility_cost_report_unit","source_fqn":"medicare_silver.facility_cost_report_unit","title":"Facility cost reports — non-acute unit-cost metrics (HHA/hospice/ESRD/FQHC/RHC)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (facility_type, ccn, fiscal-year-end, worksheet line/service metric). 946,210 rows across HHA, hospice, ESRD, FQHC, and RHC HCRIS forms.","description":"The non-acute ACTUAL-COST unit lens. Most of these HCRIS forms do NOT publish a whole-facility cost-to-charge ratio; they publish cost per visit/day/treatment. Use computed_value as the direct unit cost, multiply by claim units/days/encounters, and pass it as direct_est_cost to the RBP kernel. Do not convert these rows into fake CCRs.","identity_key":"ccn","row_count":946210,"last_updated":"2026-06-30","freshness_sla":"Annual/CMS HCRIS refresh; fiscal-year reports lag source operations.","recollection":{"cadence":"annual","watermark_field":"fy_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fy_year' is the report's fiscal-year-end vintage.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: HCRIS lags and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.facility_cost_report_unit","commercial_terms":"Public CMS data.","provenance_chain_ref":"ops/scripts/facility_hcris_cost_report_v1.py from CMS HCRIS HHA20FY{year}.ZIP, HOSPC14-REPORTS.ZIP, RNL11-REPORTS.ZIP, FQHC14-REPORTS.ZIP, and RHC17-REPORTS.ZIP; each reported unit value validated against total_cost / units where present.","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["This table is a unit-cost table, not a CCR table. Hospice/ESRD/FQHC/RHC values are direct cost per day/treatment/visit; HHA Part I values are cost per visit by discipline.","Rows with validation_ok='false' are retained for audit but must not drive pricing. As of 2026-06-30 there are 5 source formula exceptions: 3 hospice rows and 2 ESRD rows.","All columns are string (OpenCSVSerde): cast numerics on read. The RBP lookup filters validation_ok='true' and plausible='true'.","Joining requires a real facility CCN. If upstream identity only has a 10-digit NPI fallback, this table must not be guessed onto the claim."],"notes":null,"tools":[]},{"source_id":"medicare_facility_cost_report_ccr","source_fqn":"medicare_silver.facility_cost_report_ccr","title":"Facility cost reports — true non-acute cost-to-charge rows","domain":"medicare","stage":"silver","status":"live","grain":"One row per (facility_type, ccn, fiscal-year-end, worksheet line/service category) where the HCRIS form defines cost/charge/ratio cells. 26,021 rows, currently HHA Worksheet C Part II.","description":"The true non-acute CCR subset. HHA Worksheet C Part II supplies cost-to-charge ratios for medical supplies, vaccines/drugs, vaccine/drug administration, and covered disposable devices. Every row has computed_ratio = total_cost / total_charge validated against the reported ratio before it is eligible for pricing.","identity_key":"ccn","row_count":26021,"last_updated":"2026-06-30","freshness_sla":"Annual/CMS HCRIS refresh; fiscal-year reports lag source operations.","recollection":{"cadence":"annual","watermark_field":"fy_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fy_year' is the report's fiscal-year-end vintage.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: HCRIS lags and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.facility_cost_report_ccr","commercial_terms":"Public CMS data.","provenance_chain_ref":"ops/scripts/facility_hcris_cost_report_v1.py from CMS HCRIS HHA20FY{year}.ZIP Worksheet C000000 Part II; 26,021/26,021 rows validated reported_ratio == total_cost/total_charge in Athena on 2026-06-30.","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["Not a whole-HHA CCR. The form defines CCR rows only for specific supplies/drugs/devices service categories.","Rows flagged charge_as_cost='true' are non-informative and excluded from the RBP lookup.","All columns are string (OpenCSVSerde): cast numerics on read. The Athena max validation delta on 2026-06-30 was 5.000000058430487E-7."],"notes":null,"tools":[]},{"source_id":"medicare_hospital_outpatient_volume","source_fqn":"medicare_silver.hospital_outpatient_volume","title":"Hospital outpatient facility VOLUME (Medicare, by provider & service)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (ccn, Comprehensive-APC, data_year). CMS Medicare Outpatient Hospitals by Provider & Service, 2015-2023. 892,793 rows, 3,773 hospitals.","description":"The FACILITY-side outpatient volume signal: per hospital (CCN), per Comprehensive APC, the service count (srvcs) and beneficiary count, plus average submitted charge / Medicare allowed / Medicare payment. The utilization weight for distributing a hospital's measured department cost across the services it actually performs. Joins to the cost reports on ccn (95% of its CCNs have a cost report).","identity_key":"ccn","row_count":892793,"last_updated":"2026-06-16","freshness_sla":"Annual (CMS Medicare Provider Utilization release, ~2-year lag).","recollection":{"cadence":"annual","watermark_field":"fy_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fy_year' is the data year; the release lags ~2 years.","freshness_threshold/expected_delta/stale_behavior intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_outpatient_volume","commercial_terms":"Public CMS data.","provenance_chain_ref":"ops/scripts/product1_medicare_outpatient_volume_v1.py — CMS metastore -> per-year CSV (schema stable across 2015-2023).","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["GRAIN IS COMPREHENSIVE-APC, NOT HCPCS. ~70 buckets, all bundled major outpatient PROCEDURES (surgery, endoscopy, vascular, cardiac, e.g. 'Level 3 Musculoskeletal Procedures'). Simple imaging, lab, ER and clinic are NOT in this file. For per-HCPCS or imaging/lab volume, pair with the physician PUF (vlada_curated.dim_provider_service, NPI-keyed, bridge NPI->CCN). Bridge HCPCS->APC via medicare_silver.medicare_opps_rates (carries both hcpcs_code and apc).","MEDICARE ONLY: counts are Medicare fee-for-service beneficiaries, not commercial. Use as the clean volume BACKBONE / mix prior; the commercial mix proxy is the chargemaster allowed_count (partial + needs cleaning).","Early years are thinner: the Comprehensive-APC program expanded 2015-2017 (DY2015 33k rows -> DY2017+ 110k), so service-line coverage grows over time. CMS suppresses cells with <11 beneficiaries. All columns string (OpenCSVSerde); cast on read."],"notes":null,"tools":[]},{"source_id":"medicare_hcpcs_cost_center_crosswalk","source_fqn":"medicare_silver.hcpcs_cost_center_crosswalk","title":"HCPCS/CPT -> HCRIS cost-center crosswalk (the precision layer)","domain":"medicare","stage":"silver","status":"live","grain":"One row per HCPCS/CPT code. 28,328 codes -> their HCRIS 2552-10 Worksheet C cost center, so a code can be priced on the RIGHT department cost-to-charge ratio.","description":"The map that makes cost-based pricing accurate: each billing code -> the cost center where a hospital accumulates that service's cost (CT, MRI, Lab, OR, Clinic, ...). Derived from a 1.8-billion-row EMPIRICAL bridge (the modal UB-04 revenue code hospitals actually billed each code under, from our MRF) mapped through the authoritative CMS revenue-code -> cost-center spine, then adversarially validated by a sub-agent fleet (2,805 high-value codes). Join hcpcs -> cost_center_line, then use hospital_cost_report_dept for that center's CCR.","identity_key":"hcpcs","row_count":28328,"last_updated":"2026-06-15","freshness_sla":"Rebuilt when HCPCS code set or MRF revenue-code billing shifts.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reference table; rebuilt on demand, no time vintage. watermark/threshold/delta intentionally null."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hcpcs_cost_center_crosswalk","commercial_terms":"Public CMS framework + our MRF-derived empirical bridge.","provenance_chain_ref":"ops/scripts/product1_hcris_crosswalk_v1.py: empirical modal revenue code -> CMS spine -> sub-agent fleet validation.","context_doc_path":"docs/context_library/medicare/hcris_cost_reports.md","known_gaps":["confidence + method tell you how each row was derived: empirical_rc (revenue-code bridge, high) > fleet_corrected/_confirmed (sub-agent validated) > structural (CPT-section guess, no revenue-code evidence) > unmapped. Filter on confidence for cost-floor work; ~46% of codes are confidence>=0.7.","is_em_professional='true' flags E&M / professional-dominant codes (99xxx) — their cost center has a near-1.0 CCR (no facility markup) so cost-plus RBP has no arbitrage; treat as out-of-scope, not a facility price.","cost_center_line 'PROF' = purely professional/physician work with no distinct facility cost center; '' = unmapped. Neither joins to a department CCR.","The empirical bridge reflects how hospitals ACTUALLY bill (modal revenue code), which can differ from a textbook CPT->cost-center mapping; modal_share is the strength of that signal. All columns are string (OpenCSVSerde)."],"notes":null,"tools":["fair_rbp_book","fair_rbp_price"]},{"source_id":"medicare_ma_plan_payment_part_c","source_fqn":"medicare_silver.ma_plan_payment_part_c","title":"MA plan payment — Part C (contract x plan x year)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (payment_year, contract_id, plan_id). 40,014 rows, 2015-2024.","description":"CMS Part C plan-payment summary: per MA contract+plan+year, the average risk-adjusted A/B payment per member per month (avg_ab_pmpm_payment), the average enrollee risk score (avg_part_c_risk_score), and the average rebate PMPM (avg_rebate_pmpm_payment). The revenue side of MA economics.","identity_key":"contract_id","row_count":40014,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS plan payment data ZIPs; ~Feb of payment_year+2).","recollection":{"cadence":"annual","watermark_field":"payment_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'payment_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_part_c","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["JOIN KEY is the composite (contract_id, plan_id, payment_year): within one payment_year, contract_id+plan_id alone is unique. identity_key=contract_id is only the rollup anchor, NOT the full grain.","Values are AVERAGES (PMPM / mean risk score), not a contract total: multiply by member-months (enrollment) to get dollars.","Roll up to carrier via parent_org_raw on monthly_contract_enrollment_summary, NEVER a name-match."],"notes":null,"tools":[]},{"source_id":"medicare_ma_plan_payment_part_d","source_fqn":"medicare_silver.ma_plan_payment_part_d","title":"MA plan payment — Part D (plan x year)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (payment_year, contract_id, plan_id). 48,455 rows, 2015-2024.","description":"CMS Part D plan-payment reference: per plan+year averages of the federal subsidies CMS pays each MA-PD / standalone PDP (avg_direct_subsidy, avg_reinsurance, avg_low_income_cost_sharing) plus the plan's average Part D risk score (avg_part_d_risk_score).","identity_key":"contract_id","row_count":48455,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS plan payment data ZIPs; ~Feb of payment_year+2).","recollection":{"cadence":"annual","watermark_field":"payment_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'payment_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_part_d","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["JOIN KEY is the composite (payment_year, contract_id, plan_id): identity_key=contract_id is only the rollup anchor, NOT the full grain. (The auto-discovered glue stub mislabels the key as payment_year — this curated card corrects it.)","Covers MA-PD AND standalone PDP plans: filter by organization_type if you want MA-only.","Values are AVERAGES, not totals."],"notes":null,"tools":[]},{"source_id":"medicare_ma_plan_payment_county","source_fqn":"medicare_silver.ma_plan_payment_county","title":"MA plan payment — county rollup","domain":"medicare","stage":"silver","status":"live","grain":"One row per (payment_year, ssa_county_code, plan_type, snp_plan_type). 140,291 rows, 2015-2024.","description":"CMS county-level summary of MA Part C payments and risk: average PMPM federal payment, average risk score, and average rebate dollars, broken out by county, plan type, and SNP type. The public benchmark for what Medicare pays MA plans in a county.","identity_key":"ssa_county_code","row_count":140291,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS plan payment data ZIPs).","recollection":{"cadence":"annual","watermark_field":"payment_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'payment_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_county","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["COUNTY grain, NOT contract-keyed: you CANNOT join this to contract-level sources directly. Bridge to a contract via its service-area counties (medicare_silver.ma_contract_service_area).","County code is the SSA county code (ssa_county_code), not FIPS: convert before joining to FIPS-keyed sources."],"notes":null,"tools":[]},{"source_id":"medicare_dim_hcc_coefficients","source_fqn":"medicare_silver.dim_hcc_coefficients","title":"HCC risk-model coefficients (reference)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (rate_year, model_version, variable, segment) = one risk-model coefficient. 8,805 rows.","description":"CMS risk-adjustment COEFFICIENT tables (Part C HCC + Part D RxHCC). Each row is one numeric risk weight a CMS scoring engine multiplies against a member's 0/1 flag for a demographic cell or condition category, for a given payment year, model version, and population segment. A reference lookup, not contract data.","identity_key":"rate_year","row_count":8805,"last_updated":"2026-07-11","freshness_sla":"Annual (CMS risk-adjustment model updates).","recollection":{"cadence":"annual","watermark_field":"rate_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rate_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_hcc_coefficients","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Current table remains clean at 8,805 rows for payment years 2026-2027; historical coefficients are not served.","Archive recovery is complete for every payment year 2008-2025: 24 live CMS HTTP-200 artifacts, 18,151,638 bytes, zero misses, and SHA-256 pins under s3://vlada-platform-raw/medicare/bronze/hcc_coefficients_archive/py{YYYY}/; manifest: s3://vlada-platform-raw/medicare/bronze/hcc_coefficients_archive/acquisition_manifest_2026-07-11.json.","Format ground truth: NO XLS/CSV exists. Coefficients ship as fixed-width .TXT relative-factor tables with C####/F#### members inside nested SAS model-software zips; PDF duplicates ride along.","Model-version matrix: V12 era PY2008-2015; V21 first appears PY2013; V22 PY2014; V23 blend PY2019; V24 first PY2020; V28 first PY2024; 33/67 phase-in confirmed in Rate Announcement text. ESRD + RxHCC sub-packages are bundled in the same outer zips for 2009-2025.","Exact deferred lane: fixed-width SAS-text C####/F#### parser adapters plus model-version x payment-year x population-segment acceptance for community/institutional/new-enrollee segments, ESRD dialysis/graft semantics, RxHCC, explicit PACE in/out, and ICD-9-era mapping pre-2016; then per-year dry-run expected counts, zero duplicate certified keys, and idempotent rerun proof. Consumers must not read historical coefficients until this acceptance (MA risk-score math guard).","Source limits: PY2008 RxHCC has no year-specific artifact (nearest 2006/2007-vintage files); PY2010 standalone ESRD is covered only by combined ESRD_2010_2011_Software.zip published under PY2011. Normalization factors are not in these files and require a separate authoritative source decision.","REFERENCE table (not contract-keyed): the lookup key is the composite (variable, model_version, rate_year, segment) and all four grain columns are required.","Reached from dim_icd10_hcc_crosswalk: map a diagnosis to its hcc_category there, then join here on (hcc/variable, model_version, rate_year) to get the weight.","Layer-2 tool: get_risk_model."],"notes":null,"tools":[]},{"source_id":"medicare_dim_icd10_hcc_crosswalk","source_fqn":"medicare_silver.dim_icd10_hcc_crosswalk","title":"ICD-10 to HCC crosswalk (reference)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (icd_code, model_version, rate_year). 171,676 rows.","description":"CMS reference crosswalk mapping each ICD-10-CM diagnosis to its Hierarchical Condition Category under a specific risk-model version and payment year. The diagnosis-to-risk-bucket dictionary behind MA / Part D risk scoring.","identity_key":"icd_code","row_count":171676,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS risk-adjustment model updates).","recollection":{"cadence":"annual","watermark_field":"rate_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'rate_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_icd10_hcc_crosswalk","commercial_terms":"Public CMS data.","provenance_chain_ref":"M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["REFERENCE crosswalk (not contract-keyed): each (icd_code, model_version, rate_year) maps to exactly ONE hcc_category.","JOIN to dim_hcc_coefficients on (hcc_category, model_version, rate_year) to turn a diagnosis into a risk weight. Always pin model_version (V22/V24/V28) and rate_year on BOTH sides: a code's HCC changes across model versions.","Layer-2 tool: get_risk_model."],"notes":null,"tools":[]},{"source_id":"medicare_landscape_all","source_fqn":"medicare_silver.landscape_all","title":"MA / Part-D Landscape (premium / MOOP / stars / service area)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (report_year, category, contract_id, plan_id, segment_id, state, county). Unified CMS Landscape 2007-2026, all categories MA/PDP/SNP/MMP/Cost.","description":"The CMS Landscape files normalized into one table across every year and plan category, tagged by category. The consumer view published ~early September, ahead of the October PBP/benefits drop: consolidated_premium, part_c/part_d premium, part_d_deductible, moop_in_network, overall_star_rating, and the county-level service area. Carries what PBP does not.","identity_key":"contract_id","row_count":null,"last_updated":"2026-06-08","freshness_sla":"Annual (CMS Landscape consumer view, ~early September for the following plan year).","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.landscape_all","commercial_terms":"Public CMS data.","provenance_chain_ref":"External CSV (OpenCSVSerde); trace_to_source via catalog_provenance_index.json.","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["FILTER BY category (MA / PDP / SNP / MMP / Cost) or you will blend plan types in one aggregate. Clean per-category views vw_landscape_* exist.","All columns are string (OpenCSVSerde): cast numerics on read. report_year is the first data column; `year` is the partition key (use report_year for analytics).","Published ~early September, ~3-4 months before the Jan enrollment files: this is the leading-indicator source for the benefit->enrollment elasticity engine."],"notes":null,"tools":[]},{"source_id":"drug_nadac","source_fqn":"drug_silver.fact_drug_acquisition_cost","title":"NADAC — National Average Drug Acquisition Cost","domain":"drug","stage":"silver","status":"partial","grain":"One row per (ndc11, observed_period_start/week, price_type). CERTIFIED 2026-06-03 (scoped — see history gap).","description":"Pharmacy ACQUISITION cost (\"what the pharmacy paid\" — a cost FLOOR, not a payment, list price, or ASP). unit_price_usd is per pricing_unit (EA/ML/GM); normalize to the same unit + package_size before comparing across NDCs.","identity_key":"ndc11","row_count":29986,"last_updated":"2026-06-03","freshness_sla":"Weekly (CMS Medicaid publishes Wednesdays).","recollection":{"cadence":"weekly","watermark_field":"observed_week","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'observed_week' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS Medicaid publishes Wednesdays; the weekly file is cumulative-per-year — filter to one as-of-date per ingest. Dec-2024 methodology break carries vintage_tag."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_acquisition_cost (is_current = true)","commercial_terms":"Public CMS Medicaid data.","provenance_chain_ref":"drug_source_registry_cache (schema/migrations/037_drug_source_registry_cache.sql)","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["COMPLETENESS SCOPE: the live Glue table holds only the CURRENT window (effective_date ~2025-06 to 2026-05, ~30k NDCs). The 2022-2026 / ~2.2M-row history the registry documents is NOT loaded — do NOT claim a multi-year NADAC trend from this table.","Dec-2024 methodology break — rows carry vintage_tag (nadac_pre/post_dec_2024).","Weekly file is cumulative-per-year; filter to one as-of-date per ingest.","NDC world, not HCPCS — crossing to ASP/commercial Part B needs an NDC<->HCPCS crosswalk."],"notes":"CERTIFIED (product1-cert-nadac-v1), honestly scoped to the current window. Acquisition cost != payment/list/net.","tools":[]},{"source_id":"drug_asp","source_fqn":"drug_silver.fact_drug_asp_quarterly#drug_asp","title":"ASP — Medicare Part B drug Average Sales Price","domain":"drug","stage":"silver","status":"live","grain":"One row per (HCPCS code, effective quarter).","description":"Medicare Part B quarterly ASP/payment-limit benchmark by HCPCS billing unit. This is the denominator for J-code drug markup analysis against commercial infusion rates.","identity_key":"hcpcs_code","row_count":18027,"last_updated":null,"freshness_sla":"Quarterly (CMS ASP pricing files).","recollection":{"cadence":"quarterly","watermark_field":"effective_period_start","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'effective_period_start' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Derived reimbursement spine; ~6-month publication lag means a fast-moving drug's ASP can be materially stale."]},"raw_queryable_via":"Tool: asp_pricing_lookup; Athena: drug_silver.fact_drug_asp_quarterly (filter is_current = true).","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/medicare/asp.md","known_gaps":["Live proof on 2026-07-03 shows 23 current quarters (2021Q1-2026Q3), 18,027 current rows, one source URL/hash per quarter, and zero duplicate current (HCPCS, quarter) groups.","Pre-2021 ASP history (2005-2020) is not resolved by the current CMS URL pattern; sampled standard URLs for 2005, 2010, and 2015 return 404 and need archive/Wayback research before any load.","CY2026 MPFS layers IRA MFP into the ASP formula; record formula vintage per quarter.","Priced per HCPCS billing unit (hcpcs_dosage), not per NDC; crosswalk and unit-normalize before NADAC/WAC comparison."],"notes":"Logical catalog alias over physical table drug_silver.fact_drug_asp_quarterly; HCPCS<->NDC crosswalk is a separate quarterly drop.","tools":[]},{"source_id":"drug_asp_quarterly","source_fqn":"drug_silver.fact_drug_asp_quarterly","title":"ASP Pricing File — Medicare Part B quarterly ASP (raw CMS drop)","domain":"drug","stage":"silver","status":"live","grain":"One row per (hcpcs_code, release_quarter).","description":"The raw CMS Medicare Part B ASP Pricing File, quarter by quarter: HCPCS payment limit (ASP+6%), coinsurance %, and the vaccine / blood / clotting-factor pricing columns. This is the physical table the asp_pricing_lookup MCP tool reads; drug_asp is the product-level logical alias over the same served table.","identity_key":"hcpcs_code","row_count":18027,"last_updated":null,"freshness_sla":"Quarterly (CMS ASP Pricing File releases).","recollection":{"cadence":"quarterly","watermark_field":"release_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'release_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","is_current flag marks the live vintage; ~6-month publication lag."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_asp_quarterly (filter is_current = true). The Medicare Part B drug benchmark — JOIN commercial fact_rate on code=hcpcs_code (HCPCS), normalize billing units.","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/medicare/asp.md","known_gaps":["23 quarters (2021Q1-2026Q3, 18,027 is_current rows) verified 2026-07-03 by Athena; one source URL/hash per quarter and zero duplicate current (HCPCS, quarter) groups.","Pre-2021 ASP history (2005-2020) is not resolved by the current CMS URL pattern; sampled standard URLs for 2005, 2010, and 2015 return 404 and need archive/Wayback research before any load.","~6-month publication lag — a fast-moving drug's published ASP can be materially stale (see medicare/asp.md).","CY2026 era break: IRA MFP layers into ASP from 2026Q1 (vintage_tag asp_2026_plus_mfp_layered) — do not draw a smooth trend across 2026Q1 for negotiated drugs.","Priced per HCPCS billing unit (hcpcs_dosage), NOT per NDC — crosswalk + unit-normalize before any NADAC/WAC comparison."],"notes":"CERTIFIED (product1-cert-asp-v1, refreshed source-truth proof 2026-07-03). One J-code -> many NDCs.","tools":[]},{"source_id":"drug_form5500_filing","source_fqn":"drug_silver.fact_form5500_filing","title":"Form 5500 filings (DOL EFAST2 main filing)","domain":"drug","stage":"silver","status":"live","grain":"One row per DOL EFAST2 Form 5500 main filing (natural key ack_id); served plan years 2009-2025. Pre-EFAST2 1999-2008 is secured but deferred to a separate legacy table family keyed by FILING_ID.","description":"DOL EBSA public Form 5500 main-filing rows. The certified EFAST2 table is served for plan years 2009-2025 through pipelines/drug/ingest/form5500_runner.py; all pre-EFAST2 1999-2008 archive bytes are secured but remain outside the certified EFAST2 facts pending the exact deferred legacy lane.","identity_key":"ack_id","row_count":4325747,"last_updated":"2026-07-11","freshness_sla":"Annual (DOL EFAST2 Latest archive per plan year; pre-EFAST2 files are frozen October 2010 archive bytes).","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","DOL EFAST2 Latest archive per plan year; pre-EFAST2 1999-2008 files are frozen October 2010 bytes and remain in the exact deferred legacy lane."]},"raw_queryable_via":"Athena: drug_silver.fact_form5500_filing (filter is_current = true)","commercial_terms":"Public DOL EFAST2 data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/form5500_schedule_c.md","known_gaps":["EFAST2 2009-2025 is loaded/proven at 4,325,747 filing rows; the three-table EFAST2 family totals 13,037,746 rows.","All ten pre-EFAST2 years 1999-2008 are recoverable and byte-secured: 160 files totaling 1,973,997,290 bytes, zero misses, SHA-256-pinned under s3://vlada-platform-raw/drug/bronze/form5500_efast1_archive/{year}/, with the full per-file manifest at s3://vlada-platform-raw/drug/bronze/form5500_efast1_archive/acquisition_manifest_2026-07-11.json.","Pre-EFAST2 serving is deferred: use a separate table family keyed by FILING_ID, preserve the split Schedule C main/PART1/PART2 schemas, and never merge into the certified EFAST2 facts.","Before legacy serving, run the Fargate-lane parse against archived S3 bytes with layout.txt dictionaries, add era guards to vlada/tools/employer_cpd_carve_out.py and vlada/tools/pbm_compensation_rollup.py, and require an explicit identity-layer as-of/ranking rule."],"notes":"Terminal state complete_and_served with a documented pre-EFAST2 source limit; legacy archive inventory and S3 manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/form5500.json.","tools":[]},{"source_id":"drug_form5500_service_provider","source_fqn":"drug_silver.fact_form5500_service_provider","title":"Form 5500 Schedule C service providers (PBM compensation)","domain":"drug","stage":"silver","status":"live","grain":"One row per Form 5500 Schedule C Part 1 Item 2 service provider per filing (ack_id x row_order); served plan years 2009-2025. Pre-EFAST2 1999-2008 is secured but deferred to a separate legacy table family.","description":"DOL EFAST2 Form 5500 Schedule C Part 1 Item 2 service-provider rows served for plan years 2009-2025 through pipelines/drug/ingest/form5500_runner.py. The pre-EFAST2 Schedule C main/PART1/PART2 archive is byte-secured but is not merged into this certified EFAST2 table.","identity_key":"ack_id","row_count":4142787,"last_updated":"2026-07-11","freshness_sla":"Annual (DOL EFAST2 Latest archive per plan year).","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage/currency column on the parent filing.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Vintage is carried on the parent filing's plan_year (join on ack_id) + the is_current flag for the served EFAST2 era; pre-EFAST2 uses a separate FILING_ID legacy lane."]},"raw_queryable_via":"Athena: drug_silver.fact_form5500_service_provider (filter is_current = true)","commercial_terms":"Public DOL EFAST2 data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/form5500_schedule_c.md","known_gaps":["EFAST2 2009-2025 is loaded/proven at 4,142,787 service-provider rows; the three-table EFAST2 family totals 13,037,746 rows.","Pre-EFAST2 1999-2008 bytes are secured in 160 files totaling 1,973,997,290 bytes with zero misses and the full SHA-256/S3 manifest, but the legacy lane is intentionally deferred.","Pre-2009 keys on FILING_ID, not ACK_ID; Schedule C PART1 contains itemized provider compensation and PART2 contains terminated providers, so those schemas must remain separate from the EFAST2 service-provider fact.","Linked tools require era guards before any legacy serving; identity-layer use requires an explicit as-of/ranking rule."],"notes":"Terminal state complete_and_served for the EFAST2 era with a documented pre-EFAST2 source limit; archive manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/form5500.json.","tools":[]},{"source_id":"drug_consumer_price","source_fqn":"drug_silver.fact_drug_consumer_price","title":"Consumer cash-price reference (Cost Plus Drugs snapshot)","domain":"drug","stage":"silver","status":"partial","grain":"One row per consumer cash-price SKU (source x sku x quantity); current snapshot includes Cost Plus Drugs plus a second consumer-price source.","description":"Consumer cash-price reference table; currently a single snapshot of the Cost Plus Drugs (Mark Cuban CPD) public catalog (source='costplusdrugs'). Columns: source, ndc11, total_price_usd, quantity, retail_comparison_price_usd, drug_name, unit, source_captured_at. Read by employer_cpd_carve_out for the CPD reprice demo.","identity_key":"ndc11","row_count":2386,"last_updated":"2026-05-16","freshness_sla":"Snapshot; refreshed ad hoc from the CPD public catalog.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"source_captured_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_captured_at' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Snapshot only, no history — superseded on each ad-hoc refresh from the CPD public catalog; source_captured_at stamps the capture."]},"raw_queryable_via":"Athena: drug_silver.fact_drug_consumer_price (filter source; employer_cpd_carve_out uses source = 'costplusdrugs')","commercial_terms":"Public Cost Plus Drugs catalog prices.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/cost_plus_drugs.md","known_gaps":["snapshot only - no history; current-only, superseded on each refresh.","2,386 rows / 2 distinct sources documented in the 2026-05-19 wave-2 acceptance memo; the Cost Plus Drugs ingest alone was 2,370 variants at quantity=30.","consumer_price was DEFERRED in the 2026-05-19 wave-2 acceptance memo because 2 pre-retrofit PK duplicates remain until a post-retrofit re-fire.","Cost Plus Drugs coverage is mostly generics plus some brand/specialty; specialty coverage is not comprehensive.","ndc11 is name-based fuzzy for many SKUs; crosswalk to canonical NDC partial.","consumer cash-price reference, NOT a claims or contract price."],"notes":"Linked tool employer_cpd_carve_out (#23 only; pbm_compensation_rollup does not read it). Source-surface catalogue only - pricing is CPD's published consumer price, not a Vlada claim.","tools":[]},{"source_id":"drug_wac","source_fqn":"drug_silver.fact_drug_hcai_sb17_wac_increase","title":"WAC increases — California HCAI SB 17 notices","domain":"drug","stage":"silver","status":"partial","grain":"One row per (report_year, oshpd_id, NDC11, wac_effective_date, drug_category) increase notice; NULL drug_category coalesces to '' in the certified key (revised per the 2026-07-02 accepted gate design -- a genuine 2025 Brand/Generic publisher pair shares the old 4-column key).","description":"Event-level Wholesale Acquisition Cost increase notices with manufacturer explanations (CA HCAI SB 17). The public lens on WAC list-price actions.","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":"Monthly (HCAI updates current-year completed reports).","recollection":{"cadence":"monthly","watermark_field":"wac_effective_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'wac_effective_date' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CA HCAI updates current-year completed reports; WAC is a manufacturer LIST price, not a paid/net price."]},"raw_queryable_via":"Tool: wac_pricing_lookup; Athena: drug_silver.fact_drug_hcai_sb17_wac_increase","commercial_terms":"Public CA HCAI data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["Preserve/pad NDC as string (Excel drops leading zeros).","Full WAC coverage needs licensed FDB/Medi-Span; public is partial."],"notes":"2024-04-01 regulatory change swapped unit-sales for gross-sales-USD.","tools":[]},{"source_id":"drug_ira_mfp","source_fqn":"drug_silver.fact_drug_reimbursement#ira_mfp","title":"IRA Maximum Fair Price (CMS-negotiated)","domain":"drug","stage":"silver","status":"live","grain":"One row per valid (NDC11, IPAY program_year, MFP effective_period_start, MFP effective_period_end) negotiated MFP price period.","description":"CMS Inflation-Reduction-Act negotiated maximum fair prices. Current official selected-drug publication has valid priced periods effective in 2026 and 2027; selected-only 2028 rows are not price facts until CMS publishes MFP amounts.","identity_key":"ndc11","row_count":null,"last_updated":"2026-05-25","freshness_sla":"Annual (negotiated-list effective dates).","recollection":{"cadence":"annual","watermark_field":"program_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'program_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Cadence follows negotiated-list effective dates (first list effective Jan 1 2026)."]},"raw_queryable_via":"Tool: ira_mfp_exposure; Athena: drug_silver.fact_drug_reimbursement (filter price_type='ira_mfp' and is_current=true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/ira_mfp.md","known_gaps":["Current official 20260526 CSV has 601 raw rows: 456 with MFP values, 70 end-before-start Deselect/End Date update rows quarantined from the active price fact, and 145 selected-only 2028 rows without MFP values.","Manufacturer, negotiated_discount_pct, WAC baseline, and HCPCS are not populated by the current official selected-drug CSV in the active price fact.","Shares fact_drug_reimbursement with ASP + WAC (distinguish by price_type)."],"notes":"Implemented end-to-end (pipelines/drug/silver/ira_mfp_*); parser serves only valid MFP price intervals and profiles raw CMS update rows separately.","tools":[]},{"source_id":"drug_formularies","source_fqn":"drug_logical.fact_drug_formulary_scaffold","title":"Drug formulary coverage scaffold (superseded)","domain":"drug","stage":"silver","status":"planned","grain":"One row per (contract_id, plan_id, NDC11, observed_month).","description":"Original empty scaffold for Part D formulary coverage (never populated). Superseded by the CMS SPUF substrate — the live formulary data is in drug_silver.fact_drug_formulary (see source_id drug_spuf_formulary).","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"unknown","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Superseded empty scaffold (never populated) — use drug_spuf_formulary (drug_silver.fact_drug_formulary). No live cadence; the source is dead, so cadence is unknown by design, not by omission."]},"raw_queryable_via":"Empty scaffold — use drug_spuf_formulary (drug_silver.fact_drug_formulary) for live formulary data.","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_formulary.md","known_gaps":["Empty scaffold defined in schema/curated/008_drug_substrate_fact_tables.py; never populated.","Read by no MCP tool; the real tables are fact_drug_formulary + fact_drug_formulary_excluded."],"notes":"Retained for traceability; see docs/architecture/2026-05-17-spuf-formulary-substrate-assignment.md.","tools":[]},{"source_id":"drug_spuf_formulary","source_fqn":"drug_silver.fact_drug_formulary","title":"Part D formulary coverage (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (formulary_id, NDC11, report_quarter).","description":"NDC-grained Part D formulary coverage from CMS SPUF: tier_level_value, prior authorization, step therapy, quantity limits, and selected-drug flag across all MA-PD + PDP formularies. The coverage lens for employer audits. Resolve plan -> formulary_id via dim_part_d_plan.","identity_key":"ndc11","row_count":42858106,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release; filter is_current = true; grain is formulary (not plan)."]},"raw_queryable_via":"Tools: formulary_lens, formulary_churn, formulary_coverage_lookup; Athena: drug_silver.fact_drug_formulary","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_formulary.md","known_gaps":["29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 (enterprise_v1) — confirm latest quarter against live substrate.","~29.41% of SPUF NDCs don't resolve to dim_drug (legacy NDC gap); brand->NDC lookups miss historical NDCs.","tier_level_value is coverage, not a dollar amount; filter is_current = true."],"notes":"SPUF substrate sibling of fact_drug_formulary_excluded; grain is formulary (not plan) — many plans share a formulary_id.","tools":[]},{"source_id":"drug_spuf_formulary_excluded","source_fqn":"drug_silver.fact_drug_formulary_excluded","title":"Part D formulary exclusion list (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, drug_identifier, drug_identifier_type, report_quarter).","description":"Plan-level explicit drug-exclusion list from CMS SPUF, with tier, prior-auth, step-therapy, quantity-limit, and capped-benefit flags. The cross-cut \"which plans exclude drug X / how the exclusion list grew\" lens.","identity_key":"drug_identifier","row_count":355140,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release; filter is_current = true; drug_identifier era-flexes (RxCUI 2025+, NDC11 2019-2024)."]},"raw_queryable_via":"Tools: exclusion_lens, formulary_coverage_lookup; Athena: drug_silver.fact_drug_formulary_excluded","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_formulary.md","known_gaps":["Era-flex: drug_identifier is RxCUI (2025+) or NDC11 (2019-2024); ALWAYS filter by drug_identifier_type before matching.","29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 (enterprise_v1) — confirm latest quarter against live substrate."],"notes":"SPUF substrate sibling of fact_drug_formulary; filter is_current = true.","tools":[]},{"source_id":"drug_spuf_plan_dim","source_fqn":"drug_silver.dim_part_d_plan","title":"Part D plan dimension (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, segment_id, report_quarter).","description":"The Part D plan-identity dim from CMS SPUF: the plan -> formulary bridge and carrier/plan attribution for the whole SPUF family. Columns (from DIM_PART_D_PLAN_SCHEMA in pipelines/drug/silver/spuf_writers.py): contract_name, plan_name, formulary_id, premium, deductible, ma_region_code, pdp_region_code, snp, plan_suppressed_yn, plan_type, plus the is_current vintage flag. Resolve contract_id/plan_id -> formulary_id here before joining fact_drug_formulary. Geography (state, county_code) is NOT here — it moved to fact_part_d_plan_service_area on 2026-05-17 after Gate A.5 caught 4,587 PK collisions (one dim row was being written once per served county).","identity_key":"contract_id","row_count":160922,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release; publishes ~6 weeks after quarter close).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release (~6 weeks after quarter close); filter is_current = true."]},"raw_queryable_via":"Tools: plan_landscape, cost_share_lens, pricing_lens (+ all formulary tools resolve plan->formulary here); Athena: drug_silver.dim_part_d_plan (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_plan_pricing.md","known_gaps":["160,922 rows; 29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 (enterprise_v1) — confirm latest quarter against live substrate.","Geography is NOT on this dim — ANY state/county filter must join fact_part_d_plan_service_area.","formulary_id -> dim resolution is 100% (all 12,337 formulary-quarters resolve); pricing plan -> dim is 100% (159,984 plan-quarters)."],"notes":"SPUF plan-identity dim shared by plan_landscape, cost_share_lens, pricing_lens, and (for plan->formulary) the formulary tools; filter is_current = true.","tools":[]},{"source_id":"drug_spuf_plan_service_area","source_fqn":"drug_silver.fact_part_d_plan_service_area","title":"Part D plan service area (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, segment_id, state, county_code, report_quarter).","description":"Plan x geography fact from CMS SPUF — which counties each Part D plan serves. Split out of dim_part_d_plan on 2026-05-17 (Gate A.5) because a plan serves many counties and the source row is plan x service-area, not plan alone. Columns: contract_id, plan_id, segment_id, state, county_code (FIPS), report_quarter, plus is_current. The geographic-filter axis for plan_landscape.","identity_key":"contract_id","row_count":2387499,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release; publishes ~6 weeks after quarter close).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release (~6 weeks after quarter close); filter is_current = true."]},"raw_queryable_via":"Tool: plan_landscape; Athena: drug_silver.fact_part_d_plan_service_area (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_plan_pricing.md","known_gaps":["2,387,499 rows ([40,136..115,564] per quarter); 29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 — confirm latest quarter against live substrate.","No county_name column — county identity is the FIPS county_code only; join an external FIPS->name crosswalk for display.","Plan identity attributes (name, premium, formulary_id) are NOT here — join dim_part_d_plan on (contract_id, plan_id, segment_id, report_quarter)."],"notes":"SPUF service-area fact; PK widened from the dim per feedback_family_acceptance_standard (widen-where-structurally-needed). Filter is_current = true.","tools":[]},{"source_id":"drug_spuf_plan_cost_share","source_fqn":"drug_silver.fact_part_d_plan_cost_share","title":"Part D plan cost-share (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, segment_id, coverage_level, tier, days_supply, report_quarter).","description":"Beneficiary cost-share fact from CMS SPUF — copay/coinsurance by coverage phase x tier x days_supply. The fact stores cost as cost_type_pref (CMS enum: 1=copay/dollar, 2=coinsurance/fraction) + cost_amt_pref plus min/max and preferred/non-preferred/mail-order variants (see FACT_PART_D_PLAN_COST_SHARE_SCHEMA). coverage_level int maps (per CMS SPUF Tech Notes) 0=pre_initial/deductible, 1=initial_coverage, 2=coverage_gap (donut hole), 3=catastrophic. Carries tier_specialty_yn, ded_applies_yn, and a methodology_era stamp.","identity_key":"contract_id","row_count":4939689,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release; publishes ~6 weeks after quarter close).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release (~6 weeks after quarter close); filter is_current = true; do NOT aggregate across the CY2026 IRA Part-D redesign era boundary."]},"raw_queryable_via":"Tools: cost_share_lens, formulary_coverage_lookup; Athena: drug_silver.fact_part_d_plan_cost_share (filter is_current = true)","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_plan_pricing.md","known_gaps":["4,939,689 rows ([132,565..189,649] per quarter); 29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 — confirm latest quarter against live substrate.","IRA Part-D redesign (CY2026) eliminates the coverage gap + adds a $2,000 OOP cap: the coverage_level enum + copay structure differ structurally pre-2026 vs 2026+; do NOT aggregate across the boundary (gap_registry: ira_part_d_redesign_2026).","cost_share is beneficiary OOP, NOT a net price; cost_type_pref discriminates copay (dollars) vs coinsurance (fraction-of-allowed) — never compare the two raw amounts."],"notes":"SPUF cost-share fact; the cross-cut companion to formulary_coverage_lookup (single-(drug,plan)). Filter is_current = true.","tools":[]},{"source_id":"drug_spuf_plan_drug_pricing","source_fqn":"drug_silver.fact_part_d_plan_drug_pricing","title":"Part D plan drug pricing (CMS SPUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per (contract_id, plan_id, segment_id, ndc11, days_supply, report_quarter).","description":"Plan x NDC unit-cost fact from CMS SPUF — THE BIG ONE (~43M-61M rows/quarter). Columns: contract_id, plan_id, segment_id, ndc11, days_supply, report_quarter, unit_cost (USD), methodology_era, plus is_current. The unit-cost / pricing-trend / plan-to-plan variance axis. Resolve brand_name -> NDC via dim_drug_label (uncatalogued shared label dim) and plan identity via dim_part_d_plan.","identity_key":"ndc11","row_count":1593644611,"last_updated":"2026-05-18","freshness_sla":"Quarterly (CMS SPUF release; publishes ~6 weeks after quarter close).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS SPUF release (~6 weeks after quarter close); filter is_current = true and ALWAYS pin report_quarter (1.59B rows)."]},"raw_queryable_via":"Tools: pricing_lens, formulary_coverage_lookup; Athena: drug_silver.fact_part_d_plan_drug_pricing (filter is_current = true; ALWAYS pin report_quarter — 1.59B rows)","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/spuf_part_d_plan_pricing.md","known_gaps":["1,593,644,611 rows (1.59B; [43.1M..61.3M] per quarter); 29 quarters (2019-Q1..2026-Q1); promoted 2026-05-18 — confirm latest quarter against live substrate. ALWAYS pin report_quarter; full scans are prohibitively large.","unit_cost is a plan LIST unit cost, NOT a net (post-rebate) price — the substrate does not see confidential rebates.","Cross-era (2025->2026) pricing trends cross the IRA redesign boundary; gross unit_cost is more comparable than cost-share but flag the era break (gap_registry: ira_era_break_2026).","~29.41% of SPUF NDCs don't resolve to dim_drug (legacy NDC gap); brand_name -> NDC lookups miss historical NDCs.","PLAN<->FORMULARY/COST-SHARE JOIN RECIPE: this table keys by (contract_id, plan_id, segment_id, ndc11, days_supply, report_quarter) and ties to the MA plan via contract_id+plan_id (same keys as the MA enrollment/payment tables). fact_drug_formulary keys by FORMULARY_ID, not contract/plan (many plans share one formulary), so to attach tier/PA you must hop through dim_part_d_plan to get formulary_id. Recipe: pr JOIN drug_silver.dim_part_d_plan d ON (pr.contract_id=d.contract_id AND pr.plan_id=d.plan_id AND pr.segment_id=d.segment_id AND pr.report_quarter=d.report_quarter) JOIN drug_silver.fact_drug_formulary f ON (d.formulary_id=f.formulary_id AND pr.ndc11=f.ndc11 AND pr.report_quarter=f.report_quarter) -> f.tier_level_value (tier), f.prior_authorization_yn (PA). For member cost-share, join drug_silver.fact_part_d_plan_cost_share on (contract_id,plan_id,segment_id,report_quarter) + tier_level_value + coverage_level + days_supply. ALWAYS pin contract_id+plan_id+report_quarter. This is how an agent answers 'what does MA plan H####-### cover and charge for drug X' from raw SQL, no baked tool needed."],"notes":"SPUF pricing fact; the cross-cut companion to formulary_coverage_lookup. dim_drug_label (brand->NDC) stays uncatalogued — shared cross-cutting label dim. Filter is_current = true.","tools":[]},{"source_id":"drug_orange_book","source_fqn":"drug_silver.dim_orange_book_product","title":"FDA Orange Book (patents + exclusivity)","domain":"drug","stage":"silver","status":"live","grain":"One row per (application_number, product_id, observed_month).","description":"FDA approved-drug products with therapeutic-equivalence, patent, and exclusivity metadata. Drives generic-launch timing queries.","identity_key":"application_number","row_count":null,"last_updated":null,"freshness_sla":"Monthly (FDA Orange Book data files).","recollection":{"cadence":"monthly","watermark_field":"observed_month","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'observed_month' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","FDA Orange Book monthly data files; patent/exclusivity date formats vary across vintages."]},"raw_queryable_via":"Tool: prove_drug_patent_status; Athena: drug_silver.dim_orange_book_product","commercial_terms":"Public FDA data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["Current family repaired at 2026-07-01: product 48,381 rows; patent 21,807 and exclusivity 2,191 rows were appended with cloned provenance; 74 parser-normal rows were skipped.","Historical recovery is byte-secured at 85 artifacts / 55,702,065 bytes with zero fetch misses, but historical reads remain behind four exact era gates.","The four gates are the family-ledger guard, media-era edition labeling and dry-run matrix, UCM-era no-header parser acceptance, and EXE-era extraction plus parser/schema acceptance.","2007 has no known capture; months FDA superseded between captures are unrecoverable beyond the 85 secured states."],"notes":"Companion facts fact_orange_book_patent + fact_orange_book_exclusivity share the repaired family state; consumers preserve latest-assertion-per-key currentness and filter asserted_at = max(asserted_at).","tools":[]},{"source_id":"drug_purple_book","source_fqn":"drug_logical.dim_purple_book_product_reference","title":"FDA Purple Book (biosimilars + reference products)","domain":"drug","stage":"reference","status":"planned","grain":"One row per (BLA_number, product_id, observed_quarter).","description":"FDA licensed biological products with biosimilar interchangeability designations. The biosimilar-substitution lens.","identity_key":"bla_number","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (FDA Purple Book downloads).","recollection":{"cadence":"quarterly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Planned reference entry; the live queryable surface is drug_purple_book_silver. Watermark column not yet pinned (full quarter-over-quarter ingestion pending)."]},"raw_queryable_via":null,"commercial_terms":"Public FDA data.","provenance_chain_ref":"drug_source_registry_cache (planned)","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["Minimal silver promoted (drug_silver.dim_purple_book_product, catalogued as drug_purple_book_silver); full quarter-over-quarter snapshot ingestion still pending.","Interchangeability designation must be tracked quarter-over-quarter."],"notes":"Reference-domain logical entry; the live queryable surface is the silver table drug_purple_book_silver. Status planned in the drug source catalog (phase_4_plus).","tools":[]},{"source_id":"drug_purple_book_silver","source_fqn":"drug_silver.dim_purple_book_product","title":"FDA Purple Book — licensed biologics + biosimilars (silver)","domain":"drug","stage":"silver","status":"partial","grain":"One row per (bla_number, product_number) per snapshot.","description":"The promoted silver Purple Book: FDA licensed biological products with license_type (351(a) reference biologic vs 351(k) biosimilar / interchangeable), reference-product linkage, and exclusivity dates. The biosimilar-substitution lens behind the biosimilar_window MCP tool.","identity_key":"bla_number","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (FDA Purple Book downloads).","recollection":{"cadence":"quarterly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Minimal ingest — no historical snapshots yet, so a vintage/currency column is not yet tracked; interchangeability must be tracked quarter-over-quarter."]},"raw_queryable_via":"Tool: biosimilar_window; Athena: drug_silver.dim_purple_book_product","commercial_terms":"Public FDA data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["~2,255 products verified per docs/releases/2026-05-16-drug-mcp-tool-cloud-verification.md (105 reference + 126 biosimilars at that snapshot); confirm against the live substrate.","Minimal ingest — interchangeability designation must be tracked quarter-over-quarter (no historical snapshots yet)."],"notes":"Promoted silver behind the planned reference entry drug_purple_book (drug_silver.dim_purple_book_product); biosimilar_window also overlays fact_drug_spending_part_d (not catalogued in this lane).","tools":[]},{"source_id":"drug_dea_schedules","source_fqn":"drug.dea_controlled_substances","title":"DEA Controlled Substance Schedules","domain":"drug","stage":"reference","status":"planned","grain":"One row per (registrant/substance, observed_date) schedule designation.","description":"DEA Schedule II-V controlled-substance designations. Legally load-bearing flags for Part D / Sunshine analysis.","identity_key":"dea_number","row_count":null,"last_updated":null,"freshness_sla":"Event-driven (PDF snapshots).","recollection":{"cadence":"event_driven","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Planned reference entry; the live surface is drug_dea_ndc_schedule. Event-driven on DEA / Federal Register PDF snapshots — no fixed clock."]},"raw_queryable_via":"Tool: dea_schedule_lookup (catalog metadata + scouted parser)","commercial_terms":"Public DEA data.","provenance_chain_ref":"drug_source_registry_cache (planned)","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["NDC-level silver promoted (drug_silver.dim_dea_ndc_schedule, catalogued as drug_dea_ndc_schedule); the broader registrant/substance reference ingest is still phase_4_plus."],"notes":"Reference-domain logical entry; the live queryable surface is the silver table drug_dea_ndc_schedule. Tool surface exists; full ingest is phase_4_plus.","tools":[]},{"source_id":"drug_dea_ndc_schedule","source_fqn":"drug_silver.dim_dea_ndc_schedule","title":"DEA controlled-substance schedule by NDC (silver)","domain":"drug","stage":"silver","status":"planned","grain":"One row per (ndc11, ingredient_key) — combo drugs carry one row per ingredient.","description":"NDC-level DEA Controlled Substances Act schedule (I–V, or NULL for non-controlled / secondary-ingredient rows) with narcotic flag and DEA drug code, partitioned by csa_schedule. The legally load-bearing scheduling dimension behind the dea_schedule_lookup MCP tool.","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":"Event-driven (DEA / Federal Register snapshots).","recollection":{"cadence":"event_driven","watermark_field":"source_creation_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_creation_date' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Event-driven on DEA / Federal Register snapshots; source_creation_date is the DEA banner date, distinct from asserted_at (Vlada ingest date)."]},"raw_queryable_via":"Tool: dea_schedule_lookup; Athena: drug_silver.dim_dea_ndc_schedule","commercial_terms":"Public DEA data.","provenance_chain_ref":"drug_source_registry_cache","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":["csa_schedule is normalized Roman (I–V) or NULL; the NULL bucket holds non-controlled / secondary-ingredient rows — filter explicitly.","source_creation_date (DEA banner date) is not the same as asserted_at (Vlada ingest date)."],"notes":"Promoted silver behind the planned reference entry drug_dea_schedules (drug.dea_controlled_substances); dea_schedule_lookup also reads dim_drug_label (brand->NDC), not catalogued in this lane.","tools":[]},{"source_id":"drug_open_payments","source_fqn":"drug_silver.fact_drug_payment_to_prescriber","title":"CMS Open Payments (Sunshine Act)","domain":"drug","stage":"silver","status":"live","grain":"One row per exploded General Payment drug/biological slot at (program_year, payment_id, npi, ndc11/drug name) grain; pure device/no-drug rows are intentionally out of this drug fact.","description":"CMS Open Payments General Payment transfers from drug and device manufacturers/GPOs to covered recipients, filtered here to drug/biological payment slots and joined by NPI/NDC for conflict-of-interest and integrity analysis.","identity_key":"payment_id","row_count":56372438,"last_updated":"2026-05-19","freshness_sla":"Annual (with restatement republications).","recollection":{"cadence":"annual","watermark_field":"program_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["CMS publishes annual June releases and January/June restatements; compare both program_year and source_url/publication revision before declaring a held year current.","Current fact intentionally drops bad/missing NPIs and device-only/no-drug rows."]},"raw_queryable_via":"Tool: open_payments_prescriber_corr; Athena: drug_silver.fact_drug_payment_to_prescriber","commercial_terms":"Public CMS data.","provenance_chain_ref":"drug_silver M-2 substrate; open_payments_runner supports current data.json CSV URLs and accepted archived ZIP source-url replay by extracting OP_DTL_GNRL*.csv.","context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["Official CMS history is now verified for PY2013-PY2025; current table holds PY2020-PY2024 only.","PY2016-PY2019 and PY2025 are current-parser-compatible replay gaps after Source Acceptance Gate approval.","Held PY2020-PY2024 appear to use January 2026 publication URLs in sampled rows; CMS now exposes June 2026 restatement URLs that require controlled partition supersession, not append.","PY2013-PY2015 are official but legacy-schema gated; do not load into the current NPI/product-slot fact without a reviewed legacy adapter or Profile_ID/NPI bridge.","Open Payments transfer amount is not a drug price; filter by payment_nature/context before ranking high-dollar transfers."],"notes":"Source Truth 2026-07-02 prepared historical/restatement replay manifest; production replay remains acceptance-gated and must run on worker/Fargate due multi-GB annual files.","tools":[]},{"source_id":"provider_dim_provider","source_fqn":"vlada_curated.dim_provider","title":"NPPES provider directory","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per NPI.","description":"NPPES-derived provider directory: name, entity type (individual/org), taxonomy/specialty, location, and parent organizational NPI. Resolves any NPI emitted by a rate query.","identity_key":"npi","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Monthly (NPPES full + weekly incremental).","recollection":{"cadence":"monthly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","NPPES full monthly + weekly incremental; no single vintage column is catalogued on the dim today."]},"raw_queryable_via":"Tool: provider_substrate_lookup; Athena: vlada_curated.dim_provider","commercial_terms":"Public NPPES data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["Locality-level NPI matching is approximate (primary practice ZIP vs CMS localities)."],"notes":"entity_type 1 = individual, 2 = organization.","tools":[]},{"source_id":"provider_dim_provider_service","source_fqn":"vlada_curated.dim_provider_service","title":"Medicare PUF (NPI x HCPCS utilization)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per (npi, hcpcs_cd, place_of_service) — most recent CMS PUF observation (current cache; data_year 2021-2023 reflects per-key recency)","description":"Medicare Physician & Other Practitioners PUF — current deduped provider-service cache used by the ghost-rate filter and provider-service lookups. The cache keeps the most recent CMS PUF observation for each (npi, hcpcs_cd, place_of_service) key.","identity_key":"npi,hcpcs_cd,place_of_service","row_count":14161974,"last_updated":"2026-07-10","freshness_sla":"Annual (CMS PUF release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field data_year is the per-key recency field, not a vintage dimension."]},"raw_queryable_via":"Athena: vlada_curated.dim_provider_service","commercial_terms":"Public CMS data.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/records/provider_dim_provider_service.json","context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["Current-cache semantics: data_year is per-key recency, not a vintage dimension; do not use this table for time series.","Historical provider-service trends for 2013-2020 PUF years (~4.8GB) and 2024 availability are deferred until that product need is real; a separate year-preserving table and worker-fleet build would be required.","Do not backfill historical years through the current runner: it silently discards older observations on key collision (manifest lines 18-28)."],"notes":"14,161,974 rows; zero duplicate (npi,hcpcs_cd,place_of_service) keys; data_year 2021-2023 reflects per-key recency; single loaded_at batch. Current cache serves the ghost-rate filter and provider-service lookups, not historical trends.","tools":[]},{"source_id":"provider_dim_facility","source_fqn":"vlada_curated.dim_facility","title":"Facility dimension","domain":"provider_identity","stage":"dim","status":"partial","grain":"One row per facility (CCN/organizational NPI) with metadata.","description":"Facility-level metadata (CCN, organizational NPI, name, location) used to anchor the CCN<->NPI bridge and hospital identity spine.","identity_key":"hospital_ccn","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Updated with NPPES + hospital discovery.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Facility dim: updated with NPPES + hospital discovery — cadence follows its upstreams."]},"raw_queryable_via":"Athena: vlada_curated.dim_facility","commercial_terms":"Public NPPES/CMS data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":[],"notes":null,"tools":[]},{"source_id":"cms_pos_clia_lab_roster","source_fqn":"vlada_curated.dim_clia_lab","title":"CMS POS-CLIA Clinical Laboratory Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per certified CLIA laboratory (by CLIA number) per quarterly POS snapshot.","description":"CMS Provider of Services File — Clinical Laboratories (POS-CLIA): the quarterly roster of every CLIA-certified clinical laboratory in the US, published by CMS on data.cms.gov. ~103 source columns reduced to the roster spine — CLIA number, facility name(s), city/state/ZIP, composed 5-digit county FIPS, Medicare/CCN-style number, active flag (from the termination code), and the ownership/facility/certificate/lab-class category codes. Identifies and locates the lab side of diagnostic care (county join + a possible CCN bridge via CLIA_MDCR_NUM). Refreshed each quarter; the runner discovers the current CSV from data.cms.gov's data.json so it always pulls the latest quarter.","identity_key":"clia_number","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (CMS POS-CLIA quarterly files).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for the quarterly snapshot; POS-CLIA files carry no in-row quarter column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","CMS publishes POS-CLIA quarterly; the runner discovers the current quarter's CSV from data.cms.gov data.json rather than a hard-coded dated URL."]},"raw_queryable_via":"Athena: vlada_curated.dim_clia_lab (Iceberg: medicare_silver.dim_clia_lab)","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/cms_pos_clia_lab_roster.md","known_gaps":["Terminated labs remain in the file; filter is_active = true for the live roster (CLIA_TRMNTN_CD '00' = not terminated).","Category codes (control/facility/certificate/lab-classification/provider-category) are raw CMS categorical codes, not decoded labels.","CLIA_MDCR_NUM (Medicare/CCN-style number) is frequently blank and is not a validated CCN bridge until joined + verified against the facility spine.","county_fips is null when either FIPS_STATE_CD or FIPS_CNTY_CD is blank — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_clia_lab, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256).","tools":[]},{"source_id":"cms_pos_asc_roster","source_fqn":"vlada_curated.dim_asc","title":"CMS POS Ambulatory Surgical Center Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified ambulatory surgical center (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, iQIES distribution (\"Provider of Services File - Internet Quality Improvement and Evaluation System\"): the quarterly multi-provider-type POS file, FILTERED to ASC rows (prvdr_type_id = \"11\"). ASCs were migrated off the legacy OSCAR/QIES \"Hospital_and_other\" file onto iQIES, so this is the current home of the certified-ASC roster. ~182 source columns reduced to the roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag (from pgm_trmntn_cd), provider type/subtype, ownership/control code, and ASC begin-service date. The runner discovers the current CSV from data.cms.gov's data.json so it always pulls the latest quarter.","identity_key":"ccn","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (CMS POS iQIES quarterly files).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena: vlada_curated.dim_asc (Iceberg: medicare_silver.dim_asc)","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/cms_pos_asc_roster.md","known_gaps":["ASCs are NOT in the legacy Hospital_and_other QIES file; they live in the iQIES file, filtered by prvdr_type_id = '11' (no PRVDR_CTGRY_CD column exists; the '23' category-code lore does not apply).","Terminated ASCs remain in the file; filter is_active = true for the live roster (pgm_trmntn_cd '00' = not terminated).","iQIES encodes missing values as literal 'Not Applicable'/'Not Available' strings (coerced to null); control_type_cd is currently unpopulated for ASCs.","POS is the Medicare-certified universe only; cash-only / non-Medicare surgery centers need an NPPES tail (taxonomy 261QA1903X).","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_asc, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256).","tools":[]},{"source_id":"cms_medicare_dialysis_facilities","source_fqn":"vlada_curated.dim_dialysis_facility","title":"CMS Medicare Dialysis Facilities Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per (observed_period, ccn) — 18 annual FY vintages 2009-2026.","description":"CMS Medicare Dialysis Facilities (Dialysis Facility Reports): the annual roster of every Medicare-certified dialysis facility published by CMS on data.cms.gov. The mastered base table preserves one row per (observed_period, ccn) across FY2009-FY2026; the curated source_fqn is a current-vintage view.","identity_key":"observed_period,ccn","row_count":125408,"last_updated":"2026-07-10","freshness_sla":"Annual (CMS Dialysis Facility Reports FY files).","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'observed_period' is the source vintage field; FY backfills use Jan-1 FY anchors and the pre-existing FY2026 vintage uses acquisition date 2026-06-26."]},"raw_queryable_via":"Athena: vlada_curated.dim_dialysis_facility (VIEW serving max(observed_period)); historian base table: medicare_silver.dim_dialysis_facility","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/large-wave/cms_medicare_dialysis_facilities.json","context_doc_path":"docs/context_library/medicare/cms_medicare_dialysis_facilities.md","known_gaps":["The source is a melted facility x measure file; the mastered roster keeps one row per (observed_period, ccn) and drops per-measure fact columns.","The source has no open/closed status column; is_for_profit is derived from Ownership_Type ('Unavailable' -> false).","FY2009-FY2019 rows carry era-limited fields: npi is 0% in 2009 and 42-97% in 2010-2019, while modality is 100% in all years; use the recorded field-coverage proof.","Registry uniqueness is global on (source_id, sha); all 18 SHAs are distinct, but byte-identical cross-FY files would require a registry migration.","Socrata downloads are held in memory; the medicare ASG box is sized for this source."],"notes":"The source_fqn vlada_curated.dim_dialysis_facility is a VIEW serving only the current vintage over base table medicare_silver.dim_dialysis_facility; historians must query the base table. The view pins max(observed_period), because is_current is per-CCN latest assertion and is not current-roster truth.","tools":[]},{"source_id":"mart_unified_pricing","source_fqn":"vlada_curated.mart_unified_pricing","title":"Hospital x commercial unified pricing mart","domain":"curated","stage":"mart","status":"design_locked","grain":"One row per unified (CCN/NPI, payer, code, methodology) fact with markup + methodology-compat flag.","description":"The differentiated join: hospital prices x commercial negotiated rates with provenance and a methodology-compatibility gate. markup_ratio is NULL whenever methodologies are incompatible (fiduciary-grade).","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Rebuilt per bounded slice (B0->B4); operator-gated Spark runs.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Design-locked, not yet promoted to gold; rebuilt per bounded slice (B0->B4) on operator-gated Spark runs — cadence follows the slice plan, not a clock."]},"raw_queryable_via":"Builder pipelines/spark/marts/build_mart_unified_pricing_b1.py (B1 slice); gold table not yet promoted.","commercial_terms":"Derived from public TiC + HPT.","provenance_chain_ref":"docs/architecture/2026-05-03-mart-unified-pricing-schema.md","context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["Not yet promoted to gold; B1 (Berkshire x Fallon x ~20 codes) is the live slice.","markup_ratio MUST be NULL + methodology_mismatch warning on incompatible rows."],"notes":"Governed by docs/architecture/2026-04-25-hospital-commercial-unification.md.","tools":["compare_hospital_to_payer_rates","cross_source_rate_distribution"]},{"source_id":"provenance_substrate_mrf_version","source_fqn":"dim_substrate_mrf_version","title":"Unified substrate MRF version ledger","domain":"provenance","stage":"registry","status":"live","grain":"One row per (substrate, natural_key, content_sha256) observed MRF file.","description":"Substrate-wide audit chain: every fetched MRF (commercial / hospital / medicare) gets a row with content hash, raw S3 key, parser artifact hash, and first/last-seen timestamps. The provenance backbone for receipts + replay.","identity_key":"content_sha256","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Written by substrate workers on every fetch.","recollection":{"cadence":"continuous","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","This IS the substrate provenance watermark ledger (content_sha256 + first/last-seen) that other sources recollect against; it is written on every fetch, not itself recollected on a schedule."]},"raw_queryable_via":"Postgres vlada_enterprise: dim_substrate_mrf_version","commercial_terms":"Internal provenance ledger.","provenance_chain_ref":"schema/migrations/033_dim_commercial_mrf_version.sql","context_doc_path":"docs/context_library/joins_and_gotchas.md","known_gaps":["Hospital adoption pending FA-6 migration; hospital uses dim_mrf_version (027) today."],"notes":"dim_commercial_mrf_version is a back-compat view over this table.","tools":[]},{"source_id":"provenance_medicare_source_registry","source_fqn":"medicare_source_registry_cache","title":"Medicare source registry cache","domain":"provenance","stage":"registry","status":"live","grain":"One row per (source_id, observed_period, s3_object).","description":"Postgres mirror of the medicare_silver source-registry Iceberg table — bronze manifest in queryable form for restatement detection + replay.","identity_key":"source_id","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Synced from the Iceberg registry on ingest.","recollection":{"cadence":"continuous","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Postgres mirror of the medicare_silver source-registry Iceberg table; synced on ingest; tracks cms_vintage_sequence + parse_revision + restatement chain."]},"raw_queryable_via":"Postgres vlada_enterprise: medicare_source_registry_cache","commercial_terms":"Internal provenance ledger.","provenance_chain_ref":"schema/migrations/031_medicare_source_registry_cache.sql","context_doc_path":"docs/context_library/medicare/pfs.md","known_gaps":[],"notes":"Tracks cms_vintage_sequence + parse_revision + restatement chain.","tools":[]},{"source_id":"provenance_drug_source_registry","source_fqn":"drug_source_registry_cache","title":"Drug source registry cache","domain":"provenance","stage":"registry","status":"live","grain":"One row per (source_id, observed_period, s3_object).","description":"Drug-side mirror of medicare_source_registry_cache. source_publication_date generalizes cms_publication_date (FDA / DOL / NLM / HRSA / SEC / state DOIs).","identity_key":"source_id","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Synced from the Iceberg registry on ingest.","recollection":{"cadence":"continuous","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Drug-side mirror synced on ingest; source_publication_date generalizes cms_publication_date across FDA/DOL/NLM/HRSA/SEC/state DOIs."]},"raw_queryable_via":"Postgres vlada_enterprise: drug_source_registry_cache","commercial_terms":"Internal provenance ledger.","provenance_chain_ref":"schema/migrations/037_drug_source_registry_cache.sql","context_doc_path":"docs/context_library/drug/nadac_wac_and_formulary.md","known_gaps":[],"notes":"Same column shape as migration 031, drug-specific natural-key naming.","tools":[]},{"source_id":"provenance_hospital_mrf_version","source_fqn":"dim_mrf_version","title":"Hospital MRF version ledger","domain":"provenance","stage":"registry","status":"live","grain":"One row per (hospital_ccn, content_sha256) observed HPT file.","description":"Per-MRF-fetch version tracking for the hospital substrate. fact_hospital_ chargemaster rows reference it via mrf_version_id. Detects ping-only updates.","identity_key":"hospital_ccn","row_count":null,"last_updated":"2026-05-28","freshness_sla":"Written by the hospital worker on every fetch.","recollection":{"cadence":"continuous","watermark_field":"content_sha256","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'content_sha256' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","Written by the hospital worker on every fetch; content_sha256 detects ping-only updates. Unify into dim_substrate_mrf_version pending FA-6."]},"raw_queryable_via":"Postgres vlada_enterprise: dim_mrf_version","commercial_terms":"Internal provenance ledger.","provenance_chain_ref":"schema/migrations/027_dim_mrf_version.sql","context_doc_path":"docs/context_library/hospital/fact_hospital_chargemaster.md","known_gaps":["Unify into dim_substrate_mrf_version pending FA-6 migration."],"notes":null,"tools":[]},{"source_id":"medicare_pbp_section_b13_other_services","source_fqn":"medicare_silver.pbp_section_b13_other_services","title":"PBP Section B13 — Other Services (silver)","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, segment_id, version, report_year, quarter) PBP segment record.","description":"Medicare Plan Benefit Package (PBP) Section B13 \"Other Services\" silver table, built by pipelines/medicare/ingest/pbp_runner.py from the CMS PBP SAS source into a medicare_silver Iceberg table. This is the exact source surface the PBP benefit tools read for this section; the entry catalogues table identity only, not benefit semantics.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"annual","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","PBP grain carries report_year (+ quarter); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018) and pre-2010 PK is synthesized (PBP-PK-PRE-2010).","PBP source: a null numeric benefit amount is NOT $0 — consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation; this block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"athena","commercial_terms":"public-domain (CMS)","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["row_count not pinned (null) — no checked-in artifact measures it; catalog never invents counts.","Field-level benefit semantics are governed by the PBP semantic policy + docs/skills/pbp-semantics/SKILL.md, not this entry. Null numeric amount is NOT $0.","Pre-2010 PK synthesized (PBP-PK-PRE-2010); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018), per pipelines/medicare/data/grain/."],"notes":"Source-surface catalogue only. Null numeric benefit amounts are NOT $0 and field availability is not benefit semantics; consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation. Shared by compare_pbp_benefits, find_pbp_plans_by_benefit, get_pbp_benefit, and get_pbp_consumer_reconciliation_candidates.","tools":[]},{"source_id":"medicare_pbp_section_b16_dental","source_fqn":"medicare_silver.pbp_section_b16_dental","title":"PBP Section B16 — Dental (silver)","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, segment_id, version, report_year, quarter) PBP segment record.","description":"Medicare Plan Benefit Package (PBP) Section B16 dental-benefit silver table, built by pipelines/medicare/ingest/pbp_runner.py from the CMS PBP SAS source into a medicare_silver Iceberg table. This is the exact source surface the PBP benefit tools read for this section; the entry catalogues table identity only, not benefit semantics.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"annual","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","PBP grain carries report_year (+ quarter); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018) and pre-2010 PK is synthesized (PBP-PK-PRE-2010).","PBP source: a null numeric benefit amount is NOT $0 — consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation; this block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"athena","commercial_terms":"public-domain (CMS)","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["row_count not pinned (null) — no checked-in artifact measures it; catalog never invents counts.","Field-level benefit semantics are governed by the PBP semantic policy + docs/skills/pbp-semantics/SKILL.md, not this entry. Null numeric amount is NOT $0.","Pre-2010 PK synthesized (PBP-PK-PRE-2010); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018), per pipelines/medicare/data/grain/."],"notes":"Source-surface catalogue only. Null numeric benefit amounts are NOT $0 and field availability is not benefit semantics; consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation. Shared by compare_pbp_benefits, find_pbp_plans_by_benefit, get_pbp_benefit, and get_pbp_consumer_reconciliation_candidates.","tools":[]},{"source_id":"medicare_pbp_section_b17_eye_exams_wear","source_fqn":"medicare_silver.pbp_section_b17_eye_exams_wear","title":"PBP Section B17 — Eye Exams / Eyewear (silver)","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, segment_id, version, report_year, quarter) PBP segment record.","description":"Medicare Plan Benefit Package (PBP) Section B17 eye-exam / eyewear silver table, built by pipelines/medicare/ingest/pbp_runner.py from the CMS PBP SAS source into a medicare_silver Iceberg table. This is the exact source surface the PBP benefit tools read for this section; the entry catalogues table identity only, not benefit semantics.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"annual","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","PBP grain carries report_year (+ quarter); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018) and pre-2010 PK is synthesized (PBP-PK-PRE-2010).","PBP source: a null numeric benefit amount is NOT $0 — consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation; this block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"athena","commercial_terms":"public-domain (CMS)","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["row_count not pinned (null) — no checked-in artifact measures it; catalog never invents counts.","Field-level benefit semantics are governed by the PBP semantic policy + docs/skills/pbp-semantics/SKILL.md, not this entry. Null numeric amount is NOT $0.","Pre-2010 PK synthesized (PBP-PK-PRE-2010); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018), per pipelines/medicare/data/grain/."],"notes":"Source-surface catalogue only. Null numeric benefit amounts are NOT $0 and field availability is not benefit semantics; consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation. Shared by compare_pbp_benefits, find_pbp_plans_by_benefit, get_pbp_benefit, and get_pbp_consumer_reconciliation_candidates.","tools":[]},{"source_id":"medicare_pbp_section_b18_hearing_exams_aids","source_fqn":"medicare_silver.pbp_section_b18_hearing_exams_aids","title":"PBP Section B18 — Hearing Exams / Aids (silver)","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, segment_id, version, report_year, quarter) PBP segment record.","description":"Medicare Plan Benefit Package (PBP) Section B18 hearing-exam / hearing-aid silver table, built by pipelines/medicare/ingest/pbp_runner.py from the CMS PBP SAS source into a medicare_silver Iceberg table. This is the exact source surface the PBP benefit tools read for this section; the entry catalogues table identity only, not benefit semantics.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"annual","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","PBP grain carries report_year (+ quarter); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018) and pre-2010 PK is synthesized (PBP-PK-PRE-2010).","PBP source: a null numeric benefit amount is NOT $0 — consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation; this block governs refresh cadence only, not benefit semantics."]},"raw_queryable_via":"athena","commercial_terms":"public-domain (CMS)","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/pbp_supplemental_sections.md","known_gaps":["row_count not pinned (null) — no checked-in artifact measures it; catalog never invents counts.","Field-level benefit semantics are governed by the PBP semantic policy + docs/skills/pbp-semantics/SKILL.md, not this entry. Null numeric amount is NOT $0.","Pre-2010 PK synthesized (PBP-PK-PRE-2010); quarterly grain not published pre-2018 (PBP-QUARTERLY-PRE-2018), per pipelines/medicare/data/grain/."],"notes":"Source-surface catalogue only. Null numeric benefit amounts are NOT $0 and field availability is not benefit semantics; consult docs/skills/pbp-semantics/SKILL.md before any benefit interpretation. Shared by compare_pbp_benefits, find_pbp_plans_by_benefit, get_pbp_benefit, and get_pbp_consumer_reconciliation_candidates.","tools":[]},{"source_id":"cms_pos_idtf_imaging_roster","source_fqn":"medicare_silver.dim_imaging_facility","title":"CMS PECOS Public Provider Enrollment — IDTF (imaging) Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per approved Independent Diagnostic Testing Facility enrollment (by enrollment_id) per PPEF extract.","description":"A slice of the CMS Medicare Fee-For-Service Public Provider Enrollment (PPEF) file, FILTERED to Independent Diagnostic Testing Facilities (IDTF; provider_type_cd in the 12-47 enrollment-type band). This is the imaging / diagnostic-testing leg of the care-site spine — it locates fixed-base and mobile imaging facilities that bill Medicare Part B. One PPEF extract fully restates the IDTF roster (supersession by extract, not row-level delta).","identity_key":"enrollment_id","row_count":null,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes the PPEF extract (no fixed clock).","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_imaging_facility","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_idtf_imaging_roster.md","known_gaps":["IDTF only — the PPEF file carries every Medicare-enrolled provider type, but only provider_type_cd 12-47 (IDTF) is extracted today; physicians/NPPs/hospitals/other enrollment types are NOT loaded.","PECOS-enrolled universe only; cash-only / non-Medicare imaging needs an NPPES taxonomy tail.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_imaging_facility; one extract fully restates the roster (idempotent by SHA-256). Runner: pipelines/medicare/ingest/idtf_runner.py.","tools":[]},{"source_id":"cms_facility_affiliation","source_fqn":"drug_silver.dim_facility_affiliation","title":"CMS Facility Affiliation (Doctors & Clinicians) — NPI→CCN bridge","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per clinician NPI ↔ affiliated facility (CCN) edge, partitioned by facility_type.","description":"The CMS \"Facility Affiliation\" file from the Doctors and Clinicians / Provider Data Catalog — maps each clinician NPI to the facilities they are affiliated with (Hospital, Home health agency, Hospice, SNF, etc.), carrying the facility CCN. The standing NPI→CCN affiliation bridge used for provider substrate lookups and RBP duplicate-discount screening. Partitioned by facility_type so a single category scans without a full-table read.","identity_key":"npi","row_count":null,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes the Doctors & Clinicians file.","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_facility_affiliation","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_facility_affiliation.md","known_gaps":["Affiliation is self-reported via the clinician's enrollment; absence of an edge is not proof of no relationship.","facility_type_ccn is null for facility types CMS does not CCN-key."],"notes":"Iceberg table drug_silver.dim_facility_affiliation (physically in drug_silver for M-2 envelope sharing; conceptually a provider-identity bridge). Runner: pipelines/drug/ingest/facility_affiliation_runner.py.","tools":[]},{"source_id":"hospital_dim_external_bridge","source_fqn":"vlada_curated.dim_hospital_external","title":"Hospital Identity Crosswalk — CCN ↔ NPI ↔ EIN bridge","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per hospital identity, keyed by CCN, carrying the resolved NPI and (where recovered) EIN.","description":"The hospital identity crosswalk that joins the commercial (NPI), hospital (CCN), and tax-entity (EIN) namespaces. The employer agent uses it to resolve EIN/tax-id → CCN when a claim line has no usable NPI, and the county/flywheel tools use it for CCN↔NPI dedup. Distinct from dim_hospital_identity (the broader hospital spine); this is the external-id bridge specifically.","identity_key":"ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived; rebuilt when the hospital spine / chargemaster reprocess runs.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt as a derived bridge when the hospital chargemaster/spine reprocesses; no independent publication clock."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_hospital_external","commercial_terms":"Derived from public CMS/NPPES data; freely redistributable.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/hospital_dim_external_bridge.md","known_gaps":["EIN is the weakest column — recovered from chargemaster source-URL filenames (CMS names files <EIN>_name_standardcharges) and not fully back-populated; a 2026-06 audit found EIN on ~2.7k of ~6k CCNs while NPI was ~100%. Treat null EIN as 'not recovered', not 'no EIN'.","EIN→CCN resolution is only safe on a UNIQUE match; multi-CCN tax entities (systems) must not collapse to one CCN."],"notes":"Iceberg table vlada_curated.dim_hospital_external. See memory project_hospital_identity_crosswalk_2026-06-26 for the audited counts.","tools":[]},{"source_id":"nucc_provider_taxonomy","source_fqn":"drug_silver.dim_nucc_taxonomy","title":"NUCC Healthcare Provider Taxonomy Code Set","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per NUCC taxonomy code per published version (vintage snapshot).","description":"The NUCC Healthcare Provider Taxonomy — the specialty/classification code set (e.g. 207K00000X = Allergy & Immunology) that every NPI in NPPES carries 1-N of. Decodes provider specialty for cross-vertical code lookups and provider classification. Published biannually (version <YY><M>, M=1 Jan / 2 Jul); ~900 rows. Codes are stable once issued; each version is a snapshot.","identity_key":"code","row_count":null,"last_updated":null,"freshness_sla":"Biannual (NUCC January and July releases).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date.","NUCC publishes twice a year; cadence mapped to 'derived' (no native enum for biannual) — refresh on each Jan/Jul release."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_nucc_taxonomy","commercial_terms":"Public NUCC data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/nucc_provider_taxonomy.md","known_gaps":["Definitions/notes can shift between versions; treat the full row as a vintage snapshot rather than diffing fields.","Byte-secured deferred lane: 39 artifacts / 5,289,871 bytes / zero misses under s3://vlada-platform-raw/drug/bronze/nucc_taxonomy_archive/; WPC-era discovery reaches 2000 and pre-2000 is the exact source limit."],"notes":"Iceberg table drug_silver.dim_nucc_taxonomy (physically in drug_silver for M-2 envelope sharing; conceptually a provider-identity vocabulary). Runner: pipelines/drug/ingest/nucc_taxonomy_runner.py. Legacy reads remain behind the manifest/currentness/WPC parser gate; serve snapshots by asserted_at=max(asserted_at).","tools":[]},{"source_id":"icd10cm_code_dim","source_fqn":"drug_silver.dim_icd10cm","title":"ICD-10-CM Diagnosis Code Dimension","domain":"curated","stage":"dim","status":"live","grain":"One row per (effective FY vintage, code)","description":"The full ICD-10-CM diagnosis code set (code + description) by federal fiscal-year vintage — the diagnosis vocabulary that grounds claim-line diagnosis fields, the ICD-10→HCC crosswalk, and clinical interpretation. Distinct from the medicare_dim_icd10_hcc_crosswalk (which only maps the HCC-relevant subset); this is the complete code dimension.","identity_key":"icd10cm_code","row_count":1490532,"last_updated":"2026-07-12","freshness_sla":"Annual (federal fiscal year, Oct 1 start).","recollection":{"cadence":"annual","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_icd10cm","commercial_terms":"Public CMS/CDC data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/icd10cm_code_dim.md","known_gaps":["FY2012-FY2027 are served as 16 effective-FY vintages; FY2014-FY2016 are byte-identical CMS partial-code-freeze files but remain distinct legitimate FY vintages.","FY2007/FY2009/FY2010 remain PDF-tabular+GEM-only source limits and FY2011 precursor descriptions lack the order#/billable schema; loading requires a reviewed era parser and schema mapping.","FY2028+ loads wait for CMS publication via the standard pattern and use acquisition-date asserted_at; pin an effective FY because codes change annually."],"notes":"Iceberg table drug_silver.dim_icd10cm. Runner: pipelines/drug/ingest/icd10cm_runner.py.","tools":[]},{"source_id":"icd10pcs_code_dim","source_fqn":"drug_silver.dim_icd10pcs","title":"ICD-10-PCS Inpatient Procedure Code Dimension","domain":"curated","stage":"dim","status":"live","grain":"One row per (effective FY vintage, code)","description":"The full ICD-10-PCS inpatient procedure code set (code + description) by federal fiscal-year vintage — the inpatient procedure vocabulary that feeds MS-DRG grouping logic and inpatient claim interpretation.","identity_key":"icd10pcs_code","row_count":1221444,"last_updated":"2026-07-12","freshness_sla":"Annual (federal fiscal year, Oct 1 start).","recollection":{"cadence":"annual","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_icd10pcs","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/icd10pcs_code_dim.md","known_gaps":["FY2012-FY2027 are served as 16 effective-FY vintages; FY2014/FY2015 are byte-identical CMS freeze files but remain distinct legitimate FY vintages.","FY2009/FY2010 remain CMS PDF-tabular+GEM-only source limits and FY2011 precursor descriptions lack the order#/billable schema; PCS FY2007 is unrecoverable.","FY2013 provenance is a Wayback raw capture (20140515182627); retain that provenance on the vintage.","FY2028+ loads wait for CMS publication via the standard pattern and use acquisition-date asserted_at; pin an effective FY because codes change annually."],"notes":"Iceberg table drug_silver.dim_icd10pcs. Runner: pipelines/drug/ingest/icd10pcs_runner.py.","tools":[]},{"source_id":"fda_ndc_directory","source_fqn":"drug_silver.dim_drug","title":"FDA NDC Directory (drug product dimension)","domain":"drug","stage":"dim","status":"live","grain":"One row per NDC (11-digit, product+package) — the FDA drug product/package dimension.","description":"The FDA National Drug Code Directory — the authoritative drug product dimension (NDC11, product code, package code, labeler, proprietary/ non-proprietary name, dosage form, route). The identity spine for every NDC that appears in NADAC, ASP, WAC, Part D pricing, and formulary tables.","identity_key":"ndc11","row_count":null,"last_updated":"2026-07-11","freshness_sla":"FDA refreshes the NDC Directory frequently; refreshed on fetch.","recollection":{"cadence":"continuous","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date.","FDA republishes frequently; refresh on fetch rather than a fixed enum cadence."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/drug/fda_ndc_directory.md","known_gaps":["The loaded/proven Wayback era is 2016-2022 and 2024-2025; the current table remains unchanged.","Legacy recovery ground truth is NBER's mirror at data.nber.org/fda/ndc/: the live site Akamai-403s bots, the tree is fully mirrored in Wayback, and NBER hosts literal FDA originals proven by digest identity to the FDA ziptext.exe 2000 capture.","The legacy cadence is quarterly-to-monthly 1998-2012 in old multi-table fixed-width listings/packages/firms plus ziptext.exe bundles; June 2012 is the schema transition because pre-6/2012 deliveries lack the NDC variable; modern package.txt/product.txt begins September 2013; 2014-2018 is near-weekly.","The true dark window is July 2012-August 2013: zero vintages anywhere.","The classic accessdata.fda.gov/cder/ndctext.zip has a proven zero-capture 2023 year: last pre-gap 2022-04-09, next 2024-02-05, and zero 2023 captures of any status; NBER CSV conversions show the same 2022-09 to 2024-10 gap.","Recovery inventory is 15 artifacts / 103,043,735 bytes with zero misses and SHA-256 pins under s3://vlada-platform-raw/drug/bronze/fda_ndc_archive/; manifest: s3://vlada-platform-raw/drug/bronze/fda_ndc_archive/acquisition_manifest_2026-07-11.json.","Inventory: legacy last-vintage-per-year ziptext bundles for 1999-2010 (12 years), the 2013 package.txt/product.txt transition pair, and one verified 2023-01-13 openFDA JSON snapshot (24,747,460 bytes; JSON, not pipe-delimited).","Exact deferred lane: legacy multi-table fixed-width parser and legacy-to-certified NDC11 mapping; explicit pre-6/2012 no-NDC-variable key derivation; 2011 schema/grain boundary classification; per-object URL/bytes/SHA, dry-run, duplicate-key, lineage, and idempotency proofs. The 2023 JSON partial requires an openFDA-JSON adapter and format-equivalence proof before loading.","1998 plus 2011-2012 vintages and the denser 2014-2015 weekly series are enumerated by the data.nber.org/fda/ndc/ CDX pattern with collapse=digest but are not yet byte-secured; February-December 2023 is unrecovered in every format/host."],"notes":"Iceberg table drug_silver.dim_drug. Runner: pipelines/drug/ingest/fda_ndc_directory_runner.py.","tools":[]},{"source_id":"drug_part_d_spending","source_fqn":"drug_silver.fact_drug_spending_part_d","title":"Medicare Part D Spending by Drug (PUF)","domain":"drug","stage":"silver","status":"live","grain":"One row per drug (brand/generic) per data_year — aggregate Medicare Part D spending.","description":"The Medicare Part D Spending by Drug public-use file — annual aggregate Part D spend, claim counts, beneficiary counts, and unit cost trend per drug. The macro drug-spend lens (which drugs drive Part D dollars and how unit costs move year over year), complementing the NDC-level pricing tables.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":"Annual (CMS Part D spending dashboard release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage/currency column."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_spending_part_d","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/drug/part_d_spending.md","known_gaps":["Aggregate per-drug-per-year only — no provider, plan, or beneficiary grain; not joinable to a specific NDC without the drug-name crosswalk."],"notes":"Iceberg table drug_silver.fact_drug_spending_part_d. Runner: pipelines/drug/ingest/part_d_spending_runner.py.","tools":[]},{"source_id":"ipps_wage_index","source_fqn":"vlada.rbp.ref.ipps_wage_index_2026","title":"Medicare IPPS Wage Index (geographic wage adjustment)","domain":"medicare","stage":"reference","status":"live","grain":"One row per hospital CCN — the FY IPPS wage index (with cap) applied in inpatient localization.","description":"The CMS IPPS Wage Index with Cap (FY2026), per hospital CCN — the geographic labor-cost adjustment factor used to localize the inpatient operating payment to a hospital's labor market. Bundled as a reference CSV and consumed directly by the RBP pricing engine (wage_index_for(ccn)); it is the wage-localization leg the dim_msdrg entry flags as \"not loaded\" for absolute IPPS dollars — this is where it lives.","identity_key":"ccn","row_count":3222,"last_updated":"2026-06-27","freshness_sla":"Annual (federal fiscal year, Oct 1 start).","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Refreshed by replacing the bundled CSV at each IPPS final rule; no in-row vintage column."]},"raw_queryable_via":"Python: vlada.rbp.wageindex.wage_index_for(ccn) (bundled CSV vlada/rbp/ref/ipps_wage_index_2026.csv)","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/ipps_wage_index.md","known_gaps":["Bundled reference CSV, NOT an Iceberg/Athena table — not reachable via query_substrate; reached through the RBP Python helper.","Single fiscal-year snapshot in serving (FY2026 bundled CSV); official CMS FY2026 is loaded/proven in additive medicare_silver.fact_ipps_wage_index_source_truth, and FY2006 plus FY2008-FY2026 artifacts are dry-run proven. FY2008-FY2025 are not replayed/served until asserted-date/currentness/RBP migration policy is accepted; FY2006 also needs accepted handling for 584 nonnumeric '*' wage-index source rows.","FY2026 bundled file has 3,222 rows and omits official alphanumeric CCNs; alpha-CCN policy is part of the servability gate.","Wage index alone does not yield an absolute IPPS payment without the IPPS base operating rate (also not loaded as a queryable source)."],"notes":"GATE UPGRADED 2026-07-12; source remains OPEN in gated_exact / wave_3_large_backfill with acceptance_gate_required=true. Byte-secured archive: 21/21, 28,722,357 artifacts/bytes, ZERO misses, EVERY SHA byte-identical, at s3://vlada-platform-raw/medicare/bronze/ipps_wage_index_archive/ with acquisition_manifest_2026-07-12.json. Campaign gate: Do not close the gate or replay/serve history until the accepted FQN is a queryable multi-vintage contract with fiscal year, effective period/currentness, and URL/SHA/member/sheet/row lineage; alpha CCNs are preserved as six-character strings or explicitly excluded with a tested policy (the FY2026 bundle omits 31 official alpha CCNs — a real serving-completeness defect); FY2007's four period-specific values (Aug/Sep x first/second half) have explicit semantics — never collapse silently; FY2006 '*' values retained as source markers or deliberately excluded under an approved null policy — never coerced to zero; and wage_index_for(ccn, fiscal_year) plus county_fips_for pass FY2026 numeric/alpha compatibility tests. Duplicate (fiscal_year, ccn) groups zero after the approved quarantine policy.","tools":[]},{"source_id":"cms_pos_snf_roster","source_fqn":"medicare_silver.dim_snf","title":"CMS POS Skilled Nursing Facility Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified skilled nursing facility (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, iQIES distribution — the quarterly multi-provider-type POS file, FILTERED to skilled-nursing rows (prvdr_type_id = \"20\"). Same source file as dim_asc; this is the post-acute tail the ASC runner discards. Roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag (from pgm_trmntn_cd), provider type/subtype, ownership/control code. The runner downloads the iQIES CSV once and buckets SNF/HHA/Hospice by provider type.","identity_key":"ccn","row_count":17067,"last_updated":null,"freshness_sla":"Quarterly (CMS POS iQIES quarterly files).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_snf","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_post_acute_rosters.md","known_gaps":["row_count 17067 is the Q1-2026 total; ~14,710 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_type_id = '20' confirmed empirically against POS_File_iQIES_Q1_2026.csv (sample names: nursing/rehab centers); re-confirm if CMS renumbers types.","POS is the Medicare-certified universe only; non-Medicare facilities need an NPPES tail.","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_snf, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the iQIES download with dim_hha + dim_hospice.","tools":[]},{"source_id":"cms_pos_hha_roster","source_fqn":"medicare_silver.dim_hha","title":"CMS POS Home Health Agency Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified home health agency (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, iQIES distribution — the quarterly multi-provider-type POS file, FILTERED to home-health rows (prvdr_type_id = \"3\"). Same source file as dim_asc; the post-acute tail the ASC runner discards. Roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag, provider type/subtype, ownership/control code.","identity_key":"ccn","row_count":23562,"last_updated":null,"freshness_sla":"Quarterly (CMS POS iQIES quarterly files).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_hha","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_post_acute_rosters.md","known_gaps":["row_count 23562 is the Q1-2026 total; ~12,634 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_type_id = '3' confirmed empirically against POS_File_iQIES_Q1_2026.csv (sample names: home health agencies); re-confirm if CMS renumbers types.","POS is the Medicare-certified universe only; non-Medicare agencies need an NPPES tail.","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_hha, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the iQIES download with dim_snf + dim_hospice.","tools":[]},{"source_id":"cms_pos_hospice_roster","source_fqn":"medicare_silver.dim_hospice","title":"CMS POS Hospice Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified hospice (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, iQIES distribution — the quarterly multi-provider-type POS file, FILTERED to hospice rows (prvdr_type_id = \"12\"). Same source file as dim_asc; the post-acute tail the ASC runner discards. Roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag, provider type/subtype, ownership/control code.","identity_key":"ccn","row_count":9240,"last_updated":null,"freshness_sla":"Quarterly (CMS POS iQIES quarterly files).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_hospice","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_post_acute_rosters.md","known_gaps":["row_count 9240 is the Q1-2026 total; ~6,649 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_type_id = '12' confirmed empirically against POS_File_iQIES_Q1_2026.csv (sample names: hospice & palliative care); re-confirm if CMS renumbers types.","POS is the Medicare-certified universe only; non-Medicare hospices need an NPPES tail.","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_hospice, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the iQIES download with dim_snf + dim_hha. IRF/LTCH are NOT in the iQIES file (no such prvdr_type_id) — they are a separate, unbuilt source.","tools":[]},{"source_id":"cms_pos_rhc_roster","source_fqn":"medicare_silver.dim_rhc","title":"CMS POS Rural Health Clinic Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified rural health clinic (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, legacy QIES/Hospital_and_other distribution, FILTERED to rural-health-clinic rows (prvdr_ctgry_cd = '12' and prvdr_ctgry_sbtyp_cd = '01'). Roster spine -- CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag, provider category/subtype, ownership/control code. The runner downloads the POS CSV once and buckets RHC/FQHC by category.","identity_key":"ccn","row_count":12864,"last_updated":null,"freshness_sla":"Quarterly (CMS POS hospital-file quarterly snapshots).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_rhc","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_rhc_fqhc_rosters.md","known_gaps":["row_count 12864 is the Q1-2026 total; ~5,756 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_ctgry_cd = '12' and prvdr_ctgry_sbtyp_cd = '01' verified 2026-06-30 by joining 2026 fact_provider_of_services to rhc facility_cost_report_unit CCNs (1,756 of 1,763 cost-report CCNs present in POS).","POS is the Medicare-certified roster, broader than the HCRIS unit-cost subset; cost pricing still requires a validated facility_cost_report_unit row for the resolved CCN."],"notes":"Iceberg table medicare_silver.dim_rhc, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the POS download with dim_fqhc.","tools":[]},{"source_id":"cms_pos_fqhc_roster","source_fqn":"medicare_silver.dim_fqhc","title":"CMS POS Federally Qualified Health Center Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified federally qualified health center site (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, legacy QIES/Hospital_and_other distribution, FILTERED to federally-qualified-health-center rows (prvdr_ctgry_cd = '21' and prvdr_ctgry_sbtyp_cd = '01'). Roster spine -- CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag, provider category/subtype, ownership/control code. The runner downloads the POS CSV once and buckets RHC/FQHC by category.","identity_key":"ccn","row_count":15324,"last_updated":null,"freshness_sla":"Quarterly (CMS POS hospital-file quarterly snapshots).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_fqhc","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_rhc_fqhc_rosters.md","known_gaps":["row_count 15324 is the Q1-2026 total; ~12,969 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_ctgry_cd = '21' and prvdr_ctgry_sbtyp_cd = '01' verified 2026-06-30 by joining 2026 fact_provider_of_services to fqhc facility_cost_report_unit CCNs (4,018 of 4,072 cost-report CCNs present in POS).","POS is the Medicare-certified roster, broader than the HCRIS unit-cost subset; cost pricing still requires a validated facility_cost_report_unit row for the resolved CCN."],"notes":"Iceberg table medicare_silver.dim_fqhc, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the POS download with dim_rhc.","tools":[]},{"source_id":"cms_pos_irf_roster","source_fqn":"medicare_silver.dim_irf","title":"CMS POS Inpatient Rehabilitation Facility Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified inpatient rehabilitation facility (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, the LEGACY \"Hospital_and_other\" distribution (dataset \"Provider of Services File - Quality Improvement and Evaluation System\"), FILTERED to inpatient rehabilitation facilities (prvdr_ctgry_sbtyp_cd = \"05\"). IRFs are hospital SUBTYPES, not in the iQIES file dim_asc/dim_snf read — this is the hospital-file sibling. Roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag (from pgm_trmntn_cd), provider subtype/category, ownership/control code. The runner downloads the hospital POS CSV once and buckets IRF/LTCH.","identity_key":"ccn","row_count":666,"last_updated":null,"freshness_sla":"Quarterly (CMS POS hospital-file quarterly snapshots).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_irf","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_irf_ltch_rosters.md","known_gaps":["row_count 666 is the Q1-2026 total; ~409 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_ctgry_sbtyp_cd = '05' confirmed empirically against Hospital_and_other.DATA.Q1_2026.csv (cross-checks CCN last-4 3025-3099); re-confirm if CMS renumbers subtypes.","Rehab UNITS of acute hospitals (vs freestanding IRFs) may carry the parent hospital's CCN and not appear as a distinct '05' row.","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_irf, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the hospital-POS download with dim_ltch.","tools":[]},{"source_id":"cms_pos_ltch_roster","source_fqn":"medicare_silver.dim_ltch","title":"CMS POS Long-Term Care Hospital Roster","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare-certified long-term care hospital (by CCN) per quarterly POS snapshot.","description":"CMS Provider of Services File, the LEGACY \"Hospital_and_other\" distribution, FILTERED to long-term care hospitals (prvdr_ctgry_sbtyp_cd = \"02\"). LTCHs are hospital SUBTYPES, not in the iQIES file — the hospital-file sibling of the post-acute rosters. Roster spine — CCN, facility name, city/state/ZIP, composed 5-digit county FIPS, active flag, provider subtype/category, ownership/control code.","identity_key":"ccn","row_count":655,"last_updated":null,"freshness_sla":"Quarterly (CMS POS hospital-file quarterly snapshots).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for this snapshot; the source carries no in-row period column, so freshness is judged against the publication date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_ltch","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_pos_irf_ltch_rosters.md","known_gaps":["row_count 655 is the Q1-2026 total; ~313 were active (pgm_trmntn_cd '00'). Filter is_active = true for the live roster.","prvdr_ctgry_sbtyp_cd = '02' confirmed empirically against Hospital_and_other.DATA.Q1_2026.csv (cross-checks CCN last-4 2000-2299); re-confirm if CMS renumbers subtypes.","county_fips is null when either FIPS component is blank/sentinel — never a fabricated partial code.","Historical replay remains deferred: current state_cd partition-replace writers with entity-only keys would erase current state partitions. Accept observed_period identity/partition/currentness and max(observed_period) consumer pins before replay; the NBER lane also requires the bounded three-era repeatability test."],"notes":"Iceberg table medicare_silver.dim_ltch, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256). Shares the hospital-POS download with dim_irf.","tools":[]},{"source_id":"medicare_dme_payment_by_geo","source_fqn":"medicare_silver.fact_dme_payment_by_geo","title":"Medicare DME by Geography & Service (avg allowed/payment per HCPCS)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (geography [National|State], HCPCS, rental-indicator) per data year.","description":"CMS public-use file \"Medicare Durable Medical Equipment, Devices & Supplies - by Geography and Service\" — annual, claims-derived average Medicare ALLOWED and PAYMENT per DME HCPCS at national + per-state granularity, with submitted charge, standardized payment, and provider/supplier/beneficiary/claim/service counts. This is the pragmatic Medicare DME benchmark for repricing DME claim lines (the lines that had no Medicare anchor). NOTE: it is the claims-derived average, NOT the contractual DMEPOS Fee Schedule price list (a separate quarterly cms.gov ZIP, not yet ingested).","identity_key":"hcpcs_cd","row_count":38675,"last_updated":null,"freshness_sla":"Annual (CMS DME PUF release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage/currency column (parsed from the filename)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_dme_payment_by_geo","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/medicare_dme_payment_by_geo.md","known_gaps":["Claims-DERIVED average allowed/payment, NOT the contractual DMEPOS Fee Schedule (separate quarterly cms.gov ZIP; not ingested).","row_count 38,675 is the 2023 data year (ry25 release): 1,488 HCPCS x 61 geographies (National + states/territories) x rental-indicator.","CMS suppresses small cells; treat null amounts as 'not reported', not zero.","One data year per file; multi-year history needs explicit historical --source-url backfills."],"notes":"Iceberg table medicare_silver.fact_dme_payment_by_geo, partitioned by data_year; one annual file fully restates its year (replace, idempotent by SHA-256). Data year parsed from the filename (dy23 -> 2023).","tools":[]},{"source_id":"cms_hospital_quality_measure","source_fqn":"medicare_silver.fact_hospital_quality_measure","title":"CMS Care Compare Hospital Quality Measures (mortality / readmissions / timely / infections / imaging / maternal)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (measure_source, hospital CCN, measure_id) — the measure score + bounds.","description":"Long-format hospital quality measures from the CMS Provider Data Catalog (Care Compare), unioned across SIX source datasets into one fact, partitioned by measure_source: \"Complications and Deaths\" (mortality + complication rates), \"Unplanned Hospital Visits\" (readmission / ED-return rates), \"Timely and Effective Care\" (timeliness), \"Healthcare Associated Infections\" (HAI / SIR), \"Outpatient Imaging Efficiency\" (appropriate-imaging measures), and \"Maternal Health\" (maternal-care measures). Each row carries the raw score string + a parsed score_numeric, plus compared-to-national, denominator/sample, lower/higher estimate, footnote, and the measurement start/end dates. The QUALITY axis joinable by CCN to the hospital chargemaster spine — i.e. expensive-and-low-quality detection.","identity_key":"ccn","row_count":510084,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes Care Compare (roughly quarterly).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; the measurement window is carried per-row as start_date/end_date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospital_quality_measure","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_hospital_quality.md","known_gaps":["row_count ~510,084 across 6 measure_sources: complications_deaths 95,840 + unplanned_visits 67,088 + timely_care 138,173 + healthcare_assoc_infections 172,512 + outpatient_imaging_efficiency 18,512 + maternal_health 17,959 (2026-06 release).","score is the RAW string ('Not Available' coerced to null); score_numeric is null for non-numeric scores. Always check footnote for suppression.","measure_id semantics differ per measure_source; join measure_id to its measure_name, do not compare scores across unlike measures.","HCAHPS (patient survey: question/answer/star format) + HRRP + HVBP have different shapes and are NOT in this fact (separate targeted sources / follow-up)."],"notes":"Iceberg table medicare_silver.fact_hospital_quality_measure, partitioned by measure_source; one source dataset fully restates its partition (replace, idempotent by SHA-256). One runner downloads all six by title.","tools":[]},{"source_id":"cms_hospital_general_information","source_fqn":"medicare_silver.dim_hospital_quality","title":"CMS Care Compare Hospital General Information (overall star rating per CCN)","domain":"hospital","stage":"dim","status":"live","grain":"One row per Medicare-certified hospital (by CCN) — overall star rating + type + ownership.","description":"The compact hospital quality summary from CMS Care Compare \"Hospital General Information\": one row per CCN with the headline overall star rating (1-5), hospital type, ownership, emergency-services flag, and birthing-friendly designation. The quality spine; per-measure detail lives in fact_hospital_quality_measure.","identity_key":"ccn","row_count":5432,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes Care Compare (roughly quarterly).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for the Care Compare snapshot."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_hospital_quality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/cms_hospital_quality.md","known_gaps":["row_count 5,432 hospitals (2026-06 release); only ~3,182 carry an overall_rating (rest null — too few measures or footnoted).","overall_rating is null for hospitals CMS does not rate; treat null as 'unrated', not 0."],"notes":"Iceberg table medicare_silver.dim_hospital_quality, partitioned by state_cd; replace supersession (idempotent by SHA-256). Ingested by the same build-hospital-quality runner as the measure fact.","tools":[]},{"source_id":"medicare_physician_payment_by_geo","source_fqn":"medicare_silver.fact_physician_payment_by_geo","title":"Medicare Physician & Other Practitioners by Geography (avg allowed/payment per HCPCS)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (geography [National|State], HCPCS, place-of-service) per data year.","description":"CMS public-use file \"Medicare Physician & Other Practitioners - by Geography and Service\" — annual, claims-derived average Medicare ALLOWED and PAYMENT per professional HCPCS at national + per-state granularity, split by place-of-service (F = facility, O = office/non-facility), with submitted charge, standardized payment, and provider/beneficiary/service counts. The Medicare benchmark for repricing PROFESSIONAL (physician / NPP) claim lines — the largest claim category, where geographic (GPCI) variation matters. Complements the contractual national medicare_physician_fee_schedule with geographic + actual-allowed detail.","identity_key":"hcpcs_cd","row_count":268350,"last_updated":null,"freshness_sla":"Annual (CMS Physician & Other Practitioners PUF release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage/currency column (parsed from the filename)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_physician_payment_by_geo","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/medicare_physician_payment_by_geo.md","known_gaps":["Claims-DERIVED average allowed/payment, NOT the contractual PFS rate (see medicare_physician_fee_schedule for the national fee-schedule).","row_count 268,350 is the 2024 data year (R26 release): 9,403 HCPCS x 63 geographies (National + states/territories) x place-of-service.","place_of_srvc 'F' = facility, 'O' = office/non-facility — the same split that drives PFS facility vs non-facility pricing; pick the POS matching the claim setting.","CMS suppresses small cells; treat null amounts as 'not reported', not zero. One data year per file; multi-year needs historical --source-url backfills."],"notes":"Iceberg table medicare_silver.fact_physician_payment_by_geo, partitioned by data_year; one annual file fully restates its year (replace, idempotent by SHA-256). Data year parsed from the filename (D24 -> 2024).","tools":[]},{"source_id":"medicare_inpatient_payment_by_geo","source_fqn":"medicare_silver.fact_inpatient_payment_by_geo","title":"Medicare Inpatient Hospitals by Geography (avg payments per MS-DRG)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (geography [National|State], MS-DRG) per data year.","description":"CMS public-use file \"Medicare Inpatient Hospitals - by Geography and Service\" — annual, claims-derived: discharges + avg submitted covered charge / total payment / Medicare payment per MS-DRG at national + per-state. The DRG-level Medicare INPATIENT payment benchmark — pairs with the hospital chargemaster (HPT) and the IPPS relative weights (dim_msdrg) to anchor inpatient repricing. Claims-derived averages, NOT the contractual IPPS rate tables.","identity_key":"drg_cd","row_count":331464,"last_updated":null,"freshness_sla":"Annual (CMS Inpatient Hospitals PUF release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage/currency column (parsed from the filename)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_inpatient_payment_by_geo","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/medicare_hospital_payment_by_geo.md","known_gaps":["Claims-DERIVED average payments, NOT the contractual IPPS rate tables (use dim_msdrg for IPPS relative weights).","row_count 26,571 is the 2024 data year (RY26 release): MS-DRG x national + states.","Avg_Tot_Pymt_Amt includes all payers' coordination; Avg_Mdcr_Pymt_Amt is the Medicare share. CMS suppresses small cells."],"notes":"Iceberg table medicare_silver.fact_inpatient_payment_by_geo, partitioned by data_year (replace, idempotent by SHA-256). Data year parsed from filename (DY24 -> 2024). Ingested by the same build-medicare-hospital-geo runner.","tools":[]},{"source_id":"medicare_outpatient_payment_by_geo","source_fqn":"medicare_silver.fact_outpatient_payment_by_geo","title":"Medicare Outpatient Hospitals by Geography (avg payments per APC/HCPCS)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (geography [National|State], APC or HCPCS) per data year.","description":"CMS public-use file \"Medicare Outpatient Hospitals - by Geography and Service\" — annual, claims-derived: beneficiary/service counts + avg submitted charge / Medicare allowed / Medicare payment / outlier per APC (Ambulatory Payment Classification) or HCPCS at national + per-state. The OUTPATIENT facility payment benchmark — pairs with the chargemaster to anchor outpatient repricing. Claims-derived averages, NOT the contractual OPPS rate tables.","identity_key":"apc_cd","row_count":758776,"last_updated":null,"freshness_sla":"Annual (CMS Outpatient Hospitals PUF release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage/currency column (parsed from the filename)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_outpatient_payment_by_geo","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/medicare_hospital_payment_by_geo.md","known_gaps":["Claims-DERIVED average payments, NOT the contractual OPPS rate tables.","row_count 89,021 is the 2024 data year (RY26 release): srvc_lvl is APC or HCPCS; hcpcs_cd is null on APC-level rows.","CMS suppresses small cells; treat null amounts as 'not reported', not zero."],"notes":"Iceberg table medicare_silver.fact_outpatient_payment_by_geo, partitioned by data_year (replace, idempotent by SHA-256). Data year parsed from filename (DY24 -> 2024). Ingested by the same build-medicare-hospital-geo runner.","tools":[]},{"source_id":"medicare_ipps_base_rate","source_fqn":"medicare_silver.dim_ipps_base_rate","title":"Medicare IPPS Base Rate (operating + capital standardized amounts)","domain":"medicare","stage":"dim","status":"live","grain":"One row per federal fiscal year — the national IPPS standardized base amounts.","description":"The CMS IPPS base payment rates per fiscal year: operating standardized amount, capital standardized amount, and labor-related share. The MISSING LEG that makes an ABSOLUTE Medicare inpatient dollar computable — combine with the MS-DRG relative weight (drug_silver.dim_msdrg) and the hospital wage index (vlada/rbp/ref) to localize: payment ≈ base × DRG weight × (labor_share × wage_index + non_labor_share).","identity_key":"fiscal_year","row_count":2,"last_updated":null,"freshness_sla":"Annual (IPPS final rule, federal fiscal year Oct 1).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_ipps_base_rate","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"External/Athena reference; current served table provenance is incomplete. Additive source-truth writer/runner exists for medicare_silver.fact_ipps_base_rate_source_truth and FY2026 official Table 1A-1E is loaded/proven there. FY2008-FY2026 official source URLs/SHAs/values are pinned in the source-mastery manifest, but historical replay and serving-table derivation remain gated on asserted-date, labor-share, final-rule/correction/IFC precedence, and serving-shape policy.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["Few rows (one per loaded fiscal year); load the FY matching the claim's discharge date.","Only FY2024-FY2025 are held in the served dim. FY2026 is held in the additive source-truth table with both labor-share regimes but is not yet served through this dim. FY2008-FY2023 are primary-source URL/SHA/value proven and should be written only after accepted final-rule/correction/IFC precedence, asserted-date, and effective-period metadata. FY2006-FY2007 remain source-recovery residuals.","Current builder is a hardcoded drop/recreate reference script with source_note strings but no row-level source URL/SHA fields; do not expand without an accepted source-truth replay design."],"notes":"GATE UPGRADED 2026-07-12; source remains OPEN in gated_exact / wave_3_large_backfill with acceptance_gate_required=true. Byte-secured archive: 19/19, 252,953 artifacts/bytes, ZERO misses, EVERY SHA byte-identical, at s3://vlada-platform-raw/medicare/bronze/ipps_base_rate_archive/ with acquisition_manifest_2026-07-12.json. Campaign gate: Do not close the gate or mutate medicare_silver.dim_ipps_base_rate until every served FY has secured source bytes (now done for FY2008-26) and URL/SHA/member/sheet/table-cell lineage; an accepted asserted-at, effective-period, quality/EHR-tier, and final-rule/correction/IFC precedence policy; and exactly selectable wage_index_gt_1 and wage_index_le_1 base-rate regimes. FY2010 must be period-specific (two halves). A derived compatibility view may expose the legacy five columns only when its regime/period selection is explicit. Replaces the unsafe hardcoded drop/recreate mechanism (ops/scripts/build_ipps_base_rate_reference.py). FY2006-FY2007: recovery-or-source-limit decision pending. Also fix the manifest's stale vintages block claiming FY2026 not downloaded (later per-year proof is authoritative).","tools":[]},{"source_id":"medicare_gpci_locality","source_fqn":"medicare_silver.medicare_gpci_locality","title":"Medicare GPCI by Locality (geographic practice cost indices)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (locality_number, calendar_year) — work/PE/MP GPCIs.","description":"The CMS Geographic Practice Cost Indices per Medicare locality and year: work_gpci, pe_gpci (practice expense), mp_gpci (malpractice), composite_gpci, plus frontier/HPSA flags and MAC/carrier. With the conversion factor and a code's RVUs this localizes the Physician Fee Schedule to an ABSOLUTE geographic dollar. Locality resolves from county/ZIP via the locality crosswalks.","identity_key":"locality_number","row_count":1111,"last_updated":null,"freshness_sla":"Annual (PFS final rule, calendar year).","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_gpci_locality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate for CY2017-CY2024/CY2026; CY2025 is a pre-existing RDS mirror snapshot.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["Localities are CMS payment localities, not counties; join via medicare_county_to_locality / medicare_zip_to_locality.","CY2017-CY2026 loaded/proven as of 2026-07-03. CY2003-CY2016 remains gated because legacy dual-carrier rows do not fit the certified (calendar_year, state, locality_number) target key; CY2000-CY2002 remain unresolved/source-limit."],"notes":null,"tools":[]},{"source_id":"medicare_conversion_factor","source_fqn":"medicare_silver.medicare_conversion_factor","title":"Medicare PFS Conversion Factor (by effective period)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (calendar_year, effective_date, payment_track) — payment_track null pre-2026 (single-track era), qpp/nonqpp from CY2026.","description":"The CMS Physician Fee Schedule conversion factor (dollars per RVU), keyed by calendar year, effective date, and payment track so mid-year changes and the CY2026 qpp/nonqpp split do not collapse into one scalar. Default/general serving is nonqpp, the full fee schedule; qpp applies only to qualifying APM participants.","identity_key":"calendar_year,effective_date,payment_track","row_count":27,"last_updated":"2026-07-10","freshness_sla":"Annual (PFS final rule + any mid-year legislative update).","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_conversion_factor","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"Direct CMS PPRRVU source-truth rows in medicare_silver for CY2003-CY2025 plus RVU26C qpp/nonqpp rows, with source URL/SHA/effective-period/payment-track lineage; 25 pre-2026 rows remain payment_track NULL and the stale id=7 CY2026 seed was superseded.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["Mid-year legislative CF changes can produce more than one effective value per year; joins must honor effective_date/end_date.","CY2003-CY2025 are source-truth loaded/proven from official CMS PPRRVU ZIPs; CY2010 and CY2024 each have two effective-period rows.","CY2026 serving policy is explicit: select payment_track; default/general is nonqpp, the full fee schedule, and qpp applies only to qualifying APM participants. Pre-2026 rows have payment_track NULL (single-track era).","anesthesia_cf_source_url for the 2026 rows is null pending the ops backfill patch pattern because the runner has no argument for it; anesthesia CY2003-CY2019 remains gated per docs/reference/source-audit/source-mastery/anesthesia_conversion_factor_evidence.md.","Concurrent same-year qpp/nonqpp track loads are unsafe because a stale partition merge can lose a track; serialize track loads.","RVU quarterly releases may revise values; RVU26D is expected Oct and refreshes use the same gated path.","anesthesia_conversion_factor is source-truth backfilled for CY2020-CY2025 (national anesthesia CF, ops/scripts/medicare_anesthesia_cf_backfill.py; CY2024 has two effective-period rows 20.4349 / 20.7739); CY2026 serves QP 20.599835 vs non-QP 20.49754 by payment_track, while anesthesia_cf_source_url is null pending the ops backfill patch pattern; CY2003-CY2019 stays gated (evidence pack in docs/reference/source-audit/source-mastery/anesthesia_conversion_factor_evidence.md).","rule_number/public_law are populated per effective period alongside the anesthesia CF backfill; source_file_id stays null (M-2 source_url/SHA carry provenance)."],"notes":null,"tools":[]},{"source_id":"cms_anesthesia_base_unit","source_fqn":"medicare_silver.dim_anesthesia_base_unit","title":"CMS Anesthesia Base Units (00100-01999)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (hcpcs_code, calendar_year) - the integer anesthesia base-unit count for each anesthesia CPT code, per CMS publication year.","description":"The standalone CMS Anesthesia Base Units schedule (Anesthesiologists Center ZIPs). Base units are the fixed leg of Medicare anesthesia payment: payment = (base_units + time_units) x anesthesia_conversion_factor. SEPARATE schedule - never in the PFS PPRRVU RVU file (those anesthesia rows carry status indicator J, RVU=0). A code absent from this table is 'not anesthesia-priced', not $0. Qualifying-circumstance codes (99100/99116/99135/99140) are NOT in the CMS file. calendar_year is the CMS PUBLICATION year; CMS republishes only in change years and states values are 'unchanged for CY 20xx' otherwise, so each vintage GOVERNS every service year until the next published file (encoded in effective_period_start/end): CY2014 governs 2014-2017, CY2018 governs 2018-2021, CY2022 governs 2022 onward.","identity_key":"hcpcs_code,calendar_year","row_count":1933,"last_updated":null,"freshness_sla":"Republished by CMS only when base-unit values change (irregular; live files 2010-2014, 2018, 2022).","recollection":{"cadence":"event_driven","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the CMS base-units publication year.","CMS only republishes when base-unit values change (a PFS rule event), not on a fixed calendar; a stale-vs-fresh verdict needs a live check of the Anesthesiologists Center page for a newer vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_anesthesia_base_unit - as-of a service year, use the row whose effective_period_start/end spans it (equivalently max(calendar_year) <= service_year).","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS Anesthesiologists Center base-unit ZIPs, anchor-validated (00100=5 all vintages; 00537 7->10 at CY2022) with per-file row-count guard.","context_doc_path":"docs/context_library/medicare/anesthesia_base_unit.md","known_gaps":["CMS publishes base units only in change years; unchanged calendar years carry forward the most recent vintage (encoded in the M-2 effective_period), so there is no per-year row for 2015-2017, 2019-2021, 2023-2026 - resolve as-of via effective_period.","Pre-CY2010 files are Wayback-only and are not loaded (not chased).","Qualifying-circumstance add-on codes (99100/99116/99135/99140) are absent from the CMS base-units file and are not represented here."],"notes":"Iceberg medicare_silver.dim_anesthesia_base_unit, partition by calendar_year, supersession=replace. Runner pipelines/medicare/ingest/anesthesia_base_unit_runner.py; CLI python -m pipelines.curated build-anesthesia-base-unit (worker build_anesthesia_base_unit).","tools":[]},{"source_id":"medicare_county_to_locality","source_fqn":"medicare_silver.medicare_county_to_locality","title":"Medicare PFS Locality Configuration (LOCCO)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (calendar_year, state, MAC/carrier, locality_number, official CMS Counties text) after exact duplicate source rows are dropped.","description":"Official CMS LOCCO locality-configuration rows from the PFS RVU ZIPs. The table maps each source Counties text/group to a Medicare payment locality and MAC/carrier for a year; it is not a county-FIPS crosswalk.","identity_key":"state_locality_counties_year","row_count":2381,"last_updated":"2026-07-02","freshness_sla":"Annual.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's documented vintage column.","Grain is CMS source Counties text, not individual FIPS counties."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_county_to_locality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"Official CMS PFS RVU ZIP LOCCO members -> ops/scripts/medicare_county_locality_official_backfill.py -> Iceberg; source_zip_url + source_zip_sha256 + source_member + release_label + asserted_at on rows.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["fips_state and fips_county are intentionally null because official LOCCO files publish Counties text, not FIPS codes.","Use cms_zip5_locality for ZIP-level PFS locality resolution and do not use this table as a deterministic FIPS county resolver.","Current official CMS RVU index exposes LOCCO history back to 2003; pre-2003 direct URL/CDX probes did not recover a live source file in this wave.","LOCCO-to-GPCI joins use (calendar_year,state,locality_number), not locality_number alone. Measured all-year overlap is 2,359/2,360 (99.96%); the sole mismatch is a verbatim RVU03D source conflict where 03LOCCO.csv assigns TX Fort Worth locality 03 but GPCI03.csv assigns locality 28."],"notes":null,"tools":[]},{"source_id":"medicare_zip_to_locality","source_fqn":"medicare_silver.medicare_zip_to_locality","title":"Legacy Medicare ZIP → Payment Locality Crosswalk (superseded)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (zip_code, calendar_year) → CMS payment locality (+ CBSA, rurality).","description":"Legacy RDS-mirrored ZIP-to-locality surface retained for compatibility only. It is not the canonical PFS ZIP locality resolver because it collapses big-metro ZIPs into rest-of-state localities; use cms_zip5_locality / medicare_silver.medicare_zip5_locality instead.","identity_key":"zip_code","row_count":31913,"last_updated":null,"freshness_sla":"Annual (with quarterly ZIP-locality updates).","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":[]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_zip_to_locality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["is_statewide_locality flags states with one locality; ZIP→locality can change mid-year (effective_date/end_date).","DEGRADED/SUPERSEDED: live Athena query 9a5bea83-5577-4e92-ba59-ef1579be0bf4 shows 31,913 CY2025 rows, only 64 state/locality pairs, and empty CBSA/rural/effective-date columns; query 693054c4-d019-454a-9b65-442b6438094b shows 90001 and 94110 misrouted to REST OF CALIFORNIA. Use cms_zip5_locality for canonical PFS localization.","Live recheck 1a949d2a-c655-4dc6-8996-fb7daec548fb upheld the degraded shape. Canonical replacement medicare_zip5_locality has 687,053 rows across 2011-2026, 16 hashes, zero lineage nulls (1f7658ef-38d8-4f5e-a8aa-2bbbd965c375), and zero duplicate (year,zip_code) groups (db44371c-2fef-4f91-a19c-22bb9982cd1e)."],"notes":null,"tools":[]},{"source_id":"cms_zip5_locality","source_fqn":"medicare_silver.medicare_zip5_locality","title":"CMS ZIP5 → PFS Locality Crosswalk (authoritative)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (loaded year, 5-digit ZIP) from the CMS Zip Code to Carrier Locality File (ZIP5) \\u2014 state, carrier/MAC, PFS pricing locality, rural indicator, and CMS year-quarter.","description":"The authoritative CMS Zip Code to Carrier Locality File (ZIP5) — maps every 5-digit ZIP to its Medicare PFS pricing locality (+ carrier/MAC, state, rural indicator). This is the routing table GPCI localization needs to price a professional claim to the provider's geography. It supersedes medicare_zip_to_locality, which collapsed big-metro ZIPs into rest-of-state. Annual end-of-year ZIP5 history is loaded for 2011-2025 plus the current 2026Q3 file; 94110 -> SF locality 05, 90001 -> LA 18, 10001 -> Manhattan 01.","identity_key":"zip_code","row_count":687053,"last_updated":"2026-07-02","freshness_sla":"Refreshed quarterly when CMS republishes the Zip Code to Carrier Locality File.","recollection":{"cadence":"quarterly","watermark_field":"year_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Current table stores one loaded ZIP5 file per year; richer quarterly replay is gated until the table grain changes."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_zip5_locality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"pipelines/medicare/ingest/zip5_locality_runner.py \\u2014 CMS ZIP5 fixed-width file parsed positionally, M-2 envelope (asserted_at + sha256 + source_url) on every row.","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["Annual EOY history is loaded for recovered 2011-2025 plus current 2026Q3; pre-2011 annual ZIP5 history was not recovered in this wave.","Quarterly intra-year ZIP5 files are recoverable for some years, but not loaded because the current writer replaces by year; replay requires a reviewed year_quarter/effective-period grain.","Local run could not reach medicare_source_registry_cache RDS, so registry rows were not recorded; row-level M-2 source_url/asserted_at/sha256 fields are present in Iceberg."],"notes":"Iceberg table medicare_silver.medicare_zip5_locality. Fixed-width ZIP5 layout (state 1-2, zip 3-7, carrier 8-12, locality 13-14). Read per-book by vlada/rbp/gpci.py (resolve_localities). Source-truth manifest docs/reference/source-audit/source-mastery/manifests/cms_zip5_locality_recovery_manifest.json.","tools":[]},{"source_id":"medicare_code_validity","source_fqn":"medicare_silver.dim_code_validity","title":"Code Vintage Validity (which years a billing code is valid)","domain":"curated","stage":"dim","status":"live","grain":"One row per (code, code_system) — first_year, last_year, year_count of validity.","description":"For each billing code (HCPCS/CPT/DRG/etc.) the years it is valid: first_year, last_year, and the count of years observed. The reference that lets repricing resolve a claim's code against the RIGHT vintage and flag retired/not-yet-introduced codes instead of guessing — the code-vintage gap, now grounded in data (20,523 codes).","identity_key":"code","row_count":20523,"last_updated":null,"freshness_sla":"Derived; rebuilt as code sets refresh.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt when code sets refresh; no independent publication clock."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_code_validity","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/code_vintage_and_revcode.md","known_gaps":["Validity is observed from the loaded code sets; a code absent here is unknown, not necessarily invalid."],"notes":null,"tools":[]},{"source_id":"cpt_revcode_modal","source_fqn":"medicare_silver.cpt_revcode_modal","title":"CPT/HCPCS → modal UB-04 Revenue Code mapping","domain":"curated","stage":"dim","status":"live","grain":"One row per billing_code — its modal (most-common) UB-04 revenue code + support.","description":"Empirical CPT/HCPCS → UB-04 revenue-code mapping: for each billing code, the MODAL revenue code observed, the modal count, total rows, and modal share. Lets facility lines be related to a revenue code (and vice versa) — part of the fix for revenue-only facility lines being unpriceable.","identity_key":"billing_code","row_count":null,"last_updated":null,"freshness_sla":"Derived; rebuilt from the rate/claims corpus.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Empirical modal mapping; rebuilt when the underlying corpus changes."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cpt_revcode_modal","commercial_terms":"Derived from public data.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/code_vintage_and_revcode.md","known_gaps":["Modal mapping is empirical/probabilistic (use modal_share to gauge confidence), not an authoritative NUBC crosswalk (NUBC revenue codes are copyrighted)."],"notes":null,"tools":[]},{"source_id":"oig_leie_exclusions","source_fqn":"drug_silver.dim_oig_leie","title":"OIG List of Excluded Individuals/Entities (LEIE)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per (observed_period, LEIE row_uid) active-exclusion snapshot row; current roster is the latest is_current row per row_uid.","description":"The HHS-OIG List of Excluded Individuals/Entities — providers/entities BARRED from billing federal healthcare programs, with NPI/UPIN, name or business name, exclusion type and date, and any reinstatement/waiver. The integrity / accountability layer: screen a book's providers for exclusions, and join to the facility/provider spine by NPI.","identity_key":"row_uid","row_count":249886,"last_updated":"2026-07-02","freshness_sla":"Monthly (OIG updates the LEIE monthly).","recollection":{"cadence":"monthly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; OIG refreshes monthly."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_oig_leie","commercial_terms":"Public OIG data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate; oig_leie_runner supports live or Wayback UPDATED.csv source-url replay with sha/idempotency and asserted_at stamping.","context_doc_path":"docs/context_library/medicare/regulatory_integrity_and_340b.md","known_gaps":["NPI is optional and blank for many older/individual exclusions; match on name+DOB/address/geography as a fallback (with care).","Historical UPDATED.csv snapshots are recoverable from Wayback but sparse; monthly EXCL/REIN supplements require event/tombstone semantics and must not be blindly appended as active-exclusion rows.","Reinstated entities are removed from the current UPDATED.csv roster; use monthly REIN supplements or historical snapshots for reinstatement history after the accepted event-table design lands.","Physically in drug_silver (M-2 envelope sharing); conceptually a provider-identity/integrity source."],"notes":"Source Truth 2026-07-02 prepared historical replay; production historical backfill remains acceptance-gated because full snapshots and monthly supplement events have different semantics.","tools":[]},{"source_id":"oig_corporate_integrity_agreements","source_fqn":"drug_silver.dim_hhs_oig_cia","title":"HHS-OIG Corporate Integrity Agreements (CIA)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per current OIG listing entity; historical agreement grain is not certified until identity/writer redesign.","description":"HHS-OIG Corporate Integrity Agreements — entities under a CIA following a fraud/abuse settlement, with settlement amount, location, and effective date. Accountability signal on health systems / providers (often paired with LEIE for the integrity picture).","identity_key":"entity_slug (current crosswalk only; not an agreement identity)","row_count":704,"last_updated":"2026-07-12","freshness_sla":"Event-driven (OIG posts new CIAs as settlements occur).","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; CIAs post on an external trigger."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_hhs_oig_cia","commercial_terms":"Public OIG data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/regulatory_integrity_and_340b.md","known_gaps":["OIG removes listings 10 years after effective date; current and archived current-list snapshots do not prove complete historic coverage.","CRITICAL DESIGN FINDING: entity_slug is a modern listing slug, not an agreement identity; historical appends remain blocked pending identity/writer redesign and collision quarantine.","Historical recovery is byte-secured at 1,785 artifacts / 2,526,030,458 bytes with 9 documented misses; index/PDF reconciliation by effective year remains required, including 2001 and partial 2016.","Entity matching to the facility spine is by name/location (no NPI); treat as advisory and never as a canonical agreement identity."],"notes":"Byte-secured deferred lane: historical production reads remain blocked; current 704-row rolling/current scrape remains served unchanged.","tools":[]},{"source_id":"hrsa_340b_covered_entity","source_fqn":"drug_silver.dim_hrsa_covered_entity","title":"HRSA 340B Covered Entity Registry (OPAIS)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per 340B covered entity (by id_340b).","description":"The HRSA OPAIS registry of 340B covered entities — hospitals/clinics eligible to buy outpatient drugs at 340B ceiling prices, with entity type, name/sub-name, participation status + start date, grant number, address, and contacts. Identifies 340B-eligible providers (the spread between 340B acquisition and billed price is a known overpayment vector).","identity_key":"id_340b","row_count":92814,"last_updated":null,"freshness_sla":"Refreshed when HRSA republishes OPAIS (frequent).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp for the OPAIS snapshot.","HRSA republishes OPAIS frequently; refresh on fetch (no fixed enum cadence)."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_hrsa_covered_entity","commercial_terms":"Public HRSA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/regulatory_integrity_and_340b.md","known_gaps":["Covered-entity registry only; 340B CEILING PRICES (the discounted acquisition cost) are restricted and NOT included.","Join to providers via fact_hrsa_ce_npi (id_340b -> NPI)."],"notes":null,"tools":[]},{"source_id":"hrsa_340b_entity_npi","source_fqn":"drug_silver.fact_hrsa_ce_npi","title":"HRSA 340B Covered Entity → NPI bridge","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per (340B covered entity id_340b, NPI).","description":"Bridge from each HRSA 340B covered entity (id_340b) to its associated NPI(s), with state. Lets a claim's provider NPI be checked for 340B eligibility and joined to dim_hrsa_covered_entity.","identity_key":"npi_number","row_count":null,"last_updated":null,"freshness_sla":"Refreshed with the OPAIS registry.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; refreshed with OPAIS.","Refreshed with the OPAIS registry; no fixed enum cadence."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_hrsa_ce_npi","commercial_terms":"Public HRSA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/regulatory_integrity_and_340b.md","known_gaps":["An entity can map to multiple NPIs; not every covered entity publishes an NPI."],"notes":null,"tools":[]},{"source_id":"medicare_part_d_prescriber","source_fqn":"drug_silver.fact_part_d_prescriber","title":"Medicare Part D Prescriber PUF (prescribing by provider × drug × year)","domain":"drug","stage":"silver","status":"live","grain":"One row per (prescriber NPI, drug [brand+generic], data_year).","description":"The CMS Medicare Part D Prescriber public-use file — prescribing volume and cost per prescriber, drug, and year: total_claims, 30-day fills, day supply, total_drug_cost_usd, beneficiaries, prescriber type/specialty/geography. The provider-level drug-prescribing lens (~103M rows) — outlier prescribing, drug-mix by specialty, brand-vs-generic behavior.","identity_key":"prescriber_npi","row_count":103105990,"last_updated":null,"freshness_sla":"Annual (CMS Part D Prescriber release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_part_d_prescriber","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_spend_part_b_d_va_medicaid.md","known_gaps":["~103M rows — always filter by data_year and/or prescriber_state; full scans are expensive.","CMS suppresses small cells (<11 claims); treat suppressed counts as not-reported."],"notes":null,"tools":[]},{"source_id":"medicare_drug_spending_part_b","source_fqn":"drug_silver.fact_drug_spending_part_b","title":"Medicare Part B Drug Spending (by HCPCS × year)","domain":"drug","stage":"silver","status":"live","grain":"One row per (HCPCS, data_year) — Part B drug spend + ASP price.","description":"The CMS Medicare Part B Spending by Drug public-use file — physician- administered (Part B) drug spend per HCPCS J-code per year: total_spending, dosage units, claims, beneficiaries, avg spend per unit/claim/beneficiary, the ASP price, and unit-cost trend (YoY change + CAGR). The Part B counterpart to the Part D spending PUF.","identity_key":"hcpcs_code","row_count":3164,"last_updated":null,"freshness_sla":"Annual (CMS Part B drug spending dashboard).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_spending_part_b","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_spend_part_b_d_va_medicaid.md","known_gaps":["Aggregate per-HCPCS-per-year; join to ASP/NADAC for the price detail."],"notes":null,"tools":[]},{"source_id":"drug_va_fss_price","source_fqn":"drug_silver.fact_drug_va_fss_price","title":"VA Federal Supply Schedule (FSS) drug prices","domain":"drug","stage":"silver","status":"live","grain":"One row per (NDC, contract, price_start_date) — the VA FSS contract price.","description":"VA Federal Supply Schedule drug prices by NDC — the negotiated federal contract price (price_usd, price_type), vendor, contract window, generic flag, VA class. A government-negotiated price benchmark distinct from ASP / NADAC / WAC — useful as a low-water reference for drug pricing.","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":"Refreshed when VA republishes the FSS pricing file.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; refreshed on republication."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_va_fss_price","commercial_terms":"Public VA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_spend_part_b_d_va_medicaid.md","known_gaps":["Contract prices have effective windows (price_start_date / contract_start/stop); pick the price effective on the date of interest."],"notes":null,"tools":[]},{"source_id":"drug_medicaid_rebate_product","source_fqn":"drug_silver.fact_drug_medicaid_rebate_product","title":"Medicaid Drug Rebate Program — product file","domain":"drug","stage":"silver","status":"live","grain":"One row per (NDC, data_year, data_quarter) — MDRP product attributes.","description":"The Medicaid Drug Rebate Program product file by NDC and quarter — labeler, FDA product name + application number, drug category/type, unit type, units per package, therapeutic-equivalence code, COD status. The drug-product reference for Medicaid rebate eligibility (pairs with the utilization file).","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (CMS MDRP).","recollection":{"cadence":"quarterly","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' (+ data_quarter) is the source's documented vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_medicaid_rebate_product","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_spend_part_b_d_va_medicaid.md","known_gaps":["Product attributes only — rebate dollar amounts are not public at NDC grain."],"notes":null,"tools":[]},{"source_id":"drug_medicaid_utilization","source_fqn":"drug_silver.fact_drug_medicaid_utilization","title":"Medicaid State Drug Utilization (by state × NDC × quarter)","domain":"drug","stage":"silver","status":"live","grain":"One row per (utilization_type, state, NDC, data_year, data_quarter).","description":"CMS State Drug Utilization Data — Medicaid units reimbursed, prescriptions, and total / Medicaid / non-Medicaid amounts reimbursed by state, NDC, and quarter (FFS vs MCO via utilization_type). The Medicaid DRUG spend lens by state (NOTE: this is Medicaid drug utilization, not Medicaid MEDICAL rates, which remain absent).","identity_key":"ndc11","row_count":null,"last_updated":null,"freshness_sla":"Quarterly (CMS SDUD).","recollection":{"cadence":"quarterly","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' (+ data_quarter) is the source's documented vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_medicaid_utilization","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_spend_part_b_d_va_medicaid.md","known_gaps":["suppression_used flags suppressed cells; Medicaid MEDICAL (non-drug) rates are a separate, absent source."],"notes":null,"tools":[]},{"source_id":"fda_drug_shortage","source_fqn":"drug_silver.fact_drug_shortage","title":"FDA Drug Shortages","domain":"drug","stage":"silver","status":"live","grain":"One row per drug-shortage record (by package NDC + posting).","description":"The FDA drug-shortage list — current/resolved shortages by package NDC with availability status, generic name, manufacturer, route, and openFDA enrichments (brand, RxCUI, application number). Supply-risk signal for a drug book (1,733 records).","identity_key":"package_ndc","row_count":1733,"last_updated":null,"freshness_sla":"Refreshed frequently (FDA updates the shortage list often).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; FDA refreshes frequently."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_shortage","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_safety_shortage_recall.md","known_gaps":["openFDA enrichment fields can be null when FDA can't match the NDC."],"notes":null,"tools":[]},{"source_id":"fda_drug_recall","source_fqn":"drug_silver.fact_drug_recall","title":"FDA Drug Recalls (Enforcement Reports)","domain":"drug","stage":"silver","status":"live","grain":"One row per recall (by recall_number).","description":"FDA Enforcement Reports for drug recalls — classification (Class I/II/III), status, voluntary/mandated, product description, quantity, reason for recall, recalling firm + location, distribution pattern. Quality/safety signal.","identity_key":"recall_number","row_count":null,"last_updated":null,"freshness_sla":"Weekly (FDA Enforcement Report cadence).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; weekly enforcement reports."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_recall","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_safety_shortage_recall.md","known_gaps":["Recalls are firm-reported; join to NDC is via product_description (no clean NDC on every row)."],"notes":null,"tools":[]},{"source_id":"fda_warning_letter","source_fqn":"drug_silver.fact_fda_warning_letter","title":"FDA Warning Letters","domain":"drug","stage":"silver","status":"live","grain":"One row per FDA warning letter (by letter_id).","description":"FDA warning letters — issuing office, company, subject, issue/posted dates, and response/closeout dates. Regulatory-accountability signal on manufacturers/firms (pairs with recalls + OIG for the integrity picture).","identity_key":"letter_id","row_count":null,"last_updated":null,"freshness_sla":"Refreshed as FDA posts letters.","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; posted on an external trigger."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_fda_warning_letter","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_safety_shortage_recall.md","known_gaps":["Current served data is one 2026-05-16 rolling-window XLSX snapshot: 2,571 rows with posted_date 2021-01-05..2026-04-28; it is not a 10-year archive.","Historical recovery is byte-secured at 4,672 artifacts / 264,546,608 bytes with zero fetch misses, but historical reads remain in the exact deferred lane.","CRITICAL DESIGN FINDING: historical appends are unsafe under synthesized letter_id identity, issuing_office-partitioned REPLACE, and runtime-only asserted_at/source mode; require staging or key/currentness redesign, canonical crosswalk, collision quarantine, and no fuzzy merge.","Company name is not an accepted entity join key; distinguish letter_issue_date from posted_date and prohibit cross-era response/closeout trend analysis."],"notes":"Recovery surfaces are ICECI year-index HTML, wlcfm HTML tables, and Drupal HTML; the all-agency XLS export is a proven POST non-capture.","tools":[]},{"source_id":"rxclass_class","source_fqn":"drug_silver.dim_rxclass_class","title":"NLM RxClass — drug class dimension","domain":"drug","stage":"dim","status":"live","grain":"One row per (class_id, class_type) — a drug class (ATC/EPC/MoA/…).","description":"The NLM RxClass class dimension — drug classes across class systems (ATC, Established Pharmacologic Class, Mechanism of Action, therapeutic, etc.). The vocabulary for rolling drugs up to a clinical/therapeutic class.","identity_key":"class_id","row_count":null,"last_updated":null,"freshness_sla":"Periodic (NLM RxClass updates).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; periodic NLM refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_rxclass_class","commercial_terms":"Public NLM data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["class_id is unique within a class_type; always carry class_type."],"notes":null,"tools":[]},{"source_id":"rxclass_membership","source_fqn":"drug_silver.fact_rxclass_membership","title":"NLM RxClass — drug → class membership","domain":"drug","stage":"silver","status":"live","grain":"One row per (class_id, RxCUI) — a drug-to-class membership edge.","description":"RxClass membership edges — maps each RxNorm concept (RxCUI + name + term type) to its drug class(es), with the relationship + source. Bridges NDC/drug (via RxCUI) to clinical/therapeutic classes for class-level analysis.","identity_key":"rxcui","row_count":null,"last_updated":null,"freshness_sla":"Periodic (NLM RxClass updates).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; periodic NLM refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_rxclass_membership","commercial_terms":"Public NLM data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["RxCUI→NDC requires an RxNorm NDC crosswalk; membership is RxCUI-keyed."],"notes":null,"tools":[]},{"source_id":"fda_orange_book_patent","source_fqn":"drug_silver.fact_orange_book_patent","title":"FDA Orange Book — patents","domain":"drug","stage":"silver","status":"live","grain":"One row per (application, product, patent) — Orange Book patent listing.","description":"FDA Orange Book patent listings — patents protecting approved drugs by application/product, with patent number, use code, expiry, and substance/product flags. Drives generic-entry timing analysis (when patent protection lapses).","identity_key":"patent_no","row_count":null,"last_updated":null,"freshness_sla":"Monthly (FDA Orange Book).","recollection":{"cadence":"monthly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; monthly Orange Book."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_orange_book_patent","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["Current family repaired at 2026-07-01: 21,807 patent rows were appended with cloned product provenance; 74 parser-normal rows were skipped across the repair.","Dates are text fields (patent_expire_date_text) — parse defensively.","Historical recovery is byte-secured at 85 artifacts / 55,702,065 bytes with zero fetch misses, but historical reads remain behind the family-ledger, media-era, UCM-era, and EXE-era gates."],"notes":"Patent rows are part of the repaired three-table family; 42 April patent keys can remain is_current=true when absent from July because they are delisted, so consumers use latest-assertion-per-key semantics.","tools":[]},{"source_id":"fda_orange_book_exclusivity","source_fqn":"drug_silver.fact_orange_book_exclusivity","title":"FDA Orange Book — exclusivity","domain":"drug","stage":"silver","status":"live","grain":"One row per (application, product, exclusivity_code) — market exclusivity.","description":"FDA Orange Book exclusivity periods by application/product — exclusivity code and expiry. Complements patents for generic/biosimilar entry-timing analysis.","identity_key":"exclusivity_code","row_count":null,"last_updated":null,"freshness_sla":"Monthly (FDA Orange Book).","recollection":{"cadence":"monthly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; monthly Orange Book."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_orange_book_exclusivity","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["Current family repaired at 2026-07-01: 2,191 exclusivity rows were appended with cloned product provenance; 74 parser-normal rows were skipped across the repair.","Exclusivity dates are text (exclusivity_date_text); parse defensively.","Historical recovery is byte-secured at 85 artifacts / 55,702,065 bytes with zero fetch misses, but historical reads remain behind the family-ledger, media-era, UCM-era, and EXE-era gates."],"notes":"Exclusivity rows are part of the repaired three-table family; 4 April exclusivity keys can remain is_current=true when absent from July because they are delisted, so consumers use latest-assertion-per-key semantics.","tools":[]},{"source_id":"fda_drug_label","source_fqn":"drug_silver.dim_drug_label","title":"FDA Structured Product Labels (SPL) — drug label dimension","domain":"drug","stage":"dim","status":"live","grain":"One row per SPL (by spl_id) — a drug label with safety flags.","description":"FDA Structured Product Labels — brand/generic, product NDC, product type, substance, manufacturer, and safety flags (boxed warning, pregnancy, pediatric/geriatric use, REMS). The label-level safety reference per drug.","identity_key":"product_ndc","row_count":null,"last_updated":null,"freshness_sla":"Refreshed as labels are published (DailyMed/SPL).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; refreshed on publication."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug_label","commercial_terms":"Public FDA/NLM data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["One SPL can cover multiple NDCs; spl_set_id groups label versions."],"notes":null,"tools":[]},{"source_id":"fda_drug_application","source_fqn":"drug_silver.dim_drug_application","title":"FDA Drug Applications (NDA/ANDA/BLA dimension)","domain":"drug","stage":"dim","status":"live","grain":"One row per FDA application (by application_number).","description":"FDA drug applications — application type (NDA/ANDA/BLA), sponsor, product and submission counts, earliest/latest submission dates + status. The application-level spine linking Orange Book, labels, and approvals.","identity_key":"application_number","row_count":null,"last_updated":null,"freshness_sla":"Refreshed with FDA application data.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; refreshed with FDA data."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug_application","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["application_number joins to Orange Book (appl_no) and labels (application_number)."],"notes":null,"tools":[]},{"source_id":"curated_dim_code","source_fqn":"vlada_curated.dim_code","title":"Billing Code Vocabulary (HCPCS/CPT/etc.)","domain":"curated","stage":"dim","status":"live","grain":"One row per (code, code_system) — the billing-code vocabulary.","description":"The canonical billing-code dimension: code + code_system + descriptions + effective window + source. The vocabulary tools join to for a human label on any HCPCS code. Derived CURRENT vocabulary: exact union of valid HCPCS codes across the five canonical Medicare/ASP Iceberg tables (PFS/OPPS/ASC/CLFS/ASP is_current) at pinned snapshots, fail-closed validated.","identity_key":"code","row_count":20196,"last_updated":"2026-07-10","freshness_sla":"Regenerate via load-dim-code on upstream (PFS/OPPS/ASC/CLFS/ASP) refresh.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived current vocabulary; regenerated by pipelines.curated load-dim-code, no in-row publication clock."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_code","commercial_terms":"Public CMS/AMA-derived; HCPCS public, CPT descriptions are AMA-licensed.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["CPT long descriptions are AMA-copyrighted; short/derived labels only for redistribution."],"notes":"Rebuilt + proven 2026-07-10: 20,196 rows = exact canonical union (anti-join 0 both ways), 0 malformed, semantic idempotency checksum A9DC27EFB14A92C9. source_year is descriptor provenance (2005-2026), not a publication series.","tools":[]},{"source_id":"curated_dim_geography","source_fqn":"vlada_curated.dim_geography","title":"Geography Hierarchy (ZIP → county → CBSA → CSA → state)","domain":"curated","stage":"dim","status":"live","grain":"One row per ZIP code — county/CBSA/CSA hierarchy + population/area.","description":"The geography spine: ZIP → county (FIPS) → CBSA → CSA → state, with centroid, population, and land area. The geographic join key for county/market rollups across the substrate.","identity_key":"zip_code","row_count":33791,"last_updated":null,"freshness_sla":"Annual (Census vintage).","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Census vintage; rebuilt on refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_geography","commercial_terms":"Public Census data; freely redistributable.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["ZIP→county is a best-fit (ZIPs can span counties); use for rollups, not legal boundaries."],"notes":null,"tools":[]},{"source_id":"curated_dim_care_site","source_fqn":"vlada_curated.dim_care_site","title":"Care-Site Spine (NPI/CCN-keyed facility identity)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per care site (care_site_id) — NPI/CCN, class, tier, geography.","description":"The care-site identity spine: care_site_id with NPI, CCN, legal name, NPPES taxonomy, care_site_class, tier, entity type, and geography (geo_id + county FIPS). The unifying facility identity the county/care-site fleet and pricing tools resolve against.","identity_key":"care_site_id","row_count":null,"last_updated":null,"freshness_sla":"Derived (rebuilt with roster/NPPES refresh).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt with roster/NPPES refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_care_site","commercial_terms":"Derived from public CMS/NPPES data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["care_site_class/tier are assigned by the fleet; see fact_care_site_verification for verified status."],"notes":null,"tools":["care_site_price","county_expert","county_intelligence","state_agent","state_expert"]},{"source_id":"curated_dim_ccn_cbsa","source_fqn":"vlada_curated.dim_ccn_cbsa","title":"CCN → CBSA + Wage Index crosswalk","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per hospital CCN — its CBSA, county FIPS, and IPPS wage index.","description":"Maps each hospital CCN to its geographic CBSA, county FIPS, and IPPS wage index. The bridge for wage-index localization of inpatient payment and for placing a hospital in its market.","identity_key":"ccn","row_count":null,"last_updated":null,"freshness_sla":"Annual (with the IPPS wage index).","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt with the annual wage index."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_ccn_cbsa","commercial_terms":"Public CMS data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Wage index here is the per-CCN value; the bundled FY CSV (ipps_wage_index) is the authoritative reference."],"notes":null,"tools":[]},{"source_id":"curated_dim_health_system","source_fqn":"vlada_curated.dim_health_system","title":"Health System list","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per health system (system_name) — type, HQ state, multi-facility flag.","description":"A roster of health systems with system type, HQ state, and a multi-facility flag. A lightweight system list (the richer hierarchy is dim_hospital_system).","identity_key":"system_name","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived roster."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_health_system","commercial_terms":"Derived.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["system_name is the key — normalize before joining; dim_hospital_system has the normalized hierarchy."],"notes":null,"tools":[]},{"source_id":"curated_dim_hospital_system","source_fqn":"vlada_curated.dim_hospital_system","title":"Hospital System Hierarchy (parent / ultimate parent / ownership)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per hospital system (system_id) — name, parent + ultimate-parent, ownership, EIN, HQ.","description":"The hospital-system hierarchy: normalized system name, parent_system_id and ultimate_parent_id, ownership_level + ownership_type, EIN, and HQ. A PARTIAL ownership-rollup (system → parent → ultimate parent) — the closest thing we have to ownership intelligence until the PECOS \"All Owners\" datasets are ingested.","identity_key":"system_id","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Curated ownership rollup; rebuilt on refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_hospital_system","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Parent/ultimate-parent is a curated rollup, NOT the PECOS owner-entity chain (the 'All Owners' datasets remain absent)."],"notes":null,"tools":[]},{"source_id":"curated_dim_code_billing_class","source_fqn":"vlada_curated.dim_code_billing_class","title":"Billing-code institutional-vs-professional class","domain":"curated","stage":"dim","status":"live","grain":"One row per (code_system, billing_code) — learned institutional/professional class.","description":"For each billing code, the learned billing class (institutional vs professional) from observed counts: n_institutional, n_professional, institutional_frac, learned_class. Routes a claim line to the right benchmark (facility vs professional).","identity_key":"billing_code","row_count":null,"last_updated":null,"freshness_sla":"Derived (from the rate corpus).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Empirical; rebuilt from the corpus."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_code_billing_class","commercial_terms":"Derived.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Learned/empirical (use institutional_frac as confidence), not an authoritative code-class registry."],"notes":null,"tools":[]},{"source_id":"curated_dim_state_metric","source_fqn":"vlada_curated.dim_state_metric","title":"State Metrics (demographics / health context, integrated)","domain":"curated","stage":"dim","status":"live","grain":"One row per (state_code, domain, metric, data_year) — a metric value.","description":"Integrated state-level metrics across domains (demographics, health outcomes, access) with value, unit, geo_level, source, and data_year. Backs the state-agent/state-KB context.","identity_key":"state_code","row_count":null,"last_updated":null,"freshness_sla":"Per source metric (mixed).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the per-metric vintage; sources are mixed."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_state_metric","commercial_terms":"Public (Census/CDC/CMS-derived).","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Metrics come from heterogeneous sources; always read the source + data_year per row."],"notes":null,"tools":[]},{"source_id":"curated_dim_taxonomy_procedures","source_fqn":"vlada_curated.dim_taxonomy_procedures","title":"Provider-type → procedure (HCPCS) profile","domain":"curated","stage":"dim","status":"live","grain":"One row per (provider_type, HCPCS) — provider/service volume + rank.","description":"Which HCPCS each provider type performs, with provider_count, total_services, and rank. Helps map a specialty to its typical procedures (and sanity-check provider↔procedure plausibility).","identity_key":"hcpcs_cd","row_count":null,"last_updated":null,"freshness_sla":"Derived (from utilization data).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Empirical; rebuilt from utilization."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_taxonomy_procedures","commercial_terms":"Public CMS-derived.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Empirical ranking from utilization; not an authoritative scope-of-practice mapping."],"notes":null,"tools":[]},{"source_id":"curated_provider_facility_affiliation","source_fqn":"vlada_curated.dim_provider_facility_affiliation","title":"Provider → Facility affiliation (curated)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per (clinician_npi, facility_ccn) affiliation edge.","description":"Curated clinician-NPI → facility-CCN affiliation edges (with facility_type and PAC ID). The curated provider↔facility bridge (the silver source is drug_silver.dim_facility_affiliation / cms_facility_affiliation).","identity_key":"clinician_npi","row_count":null,"last_updated":null,"freshness_sla":"Derived (with the CMS affiliation refresh).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt with the CMS affiliation refresh."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_provider_facility_affiliation","commercial_terms":"Public CMS data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["Affiliation is self-reported; absence of an edge is not proof of no relationship."],"notes":null,"tools":[]},{"source_id":"commercial_rate_provider_edge","source_fqn":"vlada_curated.rate_provider_edge","title":"Commercial rate ↔ provider (NPI) edge","domain":"commercial","stage":"curated","status":"live","grain":"One row per (rate_id, NPI) — links a negotiated rate to a provider.","description":"The normalized rate↔provider edge of the commercial substrate: rate_id → NPI (bucketed), payer, state, version, code, negotiated_rate/type. The join that attaches TiC negotiated rates to specific providers (NPI lookups).","identity_key":"rate_id","row_count":null,"last_updated":null,"freshness_sla":"Per payer MRF version.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt per payer MRF version."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.rate_provider_edge","commercial_terms":"Public TiC data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/commercial/rate_model_and_serving.md","known_gaps":["High-fanout payers explode this edge; partition-prune by payer_id/state."],"notes":null,"tools":[]},{"source_id":"commercial_mart_rate_by_entity","source_fqn":"vlada_curated.mart_rate_by_entity","title":"Commercial gold mart — rate by entity","domain":"commercial","stage":"mart","status":"live","grain":"One row per (payer, entity, code) — entity-keyed negotiated rate.","description":"Gold serving mart projecting fact_rate by negotiating entity: payer, entity, code (+prefix), negotiated_rate/type, billing_class, state. Entity-level rate serving (complements mart_rate_by_code).","identity_key":"rate_id","row_count":null,"last_updated":null,"freshness_sla":"Derived (rebuilt from silver).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt from silver."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.mart_rate_by_entity","commercial_terms":"Public TiC data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/commercial/rate_model_and_serving.md","known_gaps":["Entity rollup; for code-level serving use mart_rate_by_code."],"notes":null,"tools":[]},{"source_id":"hospital_chargemaster_comparable","source_fqn":"vlada_curated.vw_fact_hospital_chargemaster_comparable","title":"Hospital chargemaster — comparable view (real-negotiated, classified)","domain":"hospital","stage":"semantic_view","status":"live","grain":"One row per (CCN, billing_code, payer, plan, billing_class) — comparable rate.","description":"The serving view over the hospital chargemaster, FILTERED to comparable / real-negotiated rates with payer entity/plan structure resolved and a comparability class. The surface the pricing engine reads for hospital rates (backed by fact_hospital_comparability_mat).","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived (per hospital reprocess).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt on hospital reprocess."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_fact_hospital_chargemaster_comparable","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Comparable filter excludes ghost/contaminated rates; use _canonical/_validated for the fuller set."],"notes":null,"tools":[]},{"source_id":"hospital_chargemaster_canonical","source_fqn":"vlada_curated.vw_fact_hospital_chargemaster_canonical","title":"Hospital chargemaster — canonical view","domain":"hospital","stage":"semantic_view","status":"live","grain":"One row per canonical hospital rate (CCN, billing_code, payer, plan).","description":"Canonical hospital-chargemaster view: resolved code system, payer/plan, rate type, billing class, rate, gross charge. The canonicalized rate surface (broader than _comparable; before the comparability filter).","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived view."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_fact_hospital_chargemaster_canonical","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Includes rates the comparable view excludes; check rate_type/billing_class."],"notes":null,"tools":["compare_hospital_rates","compare_hospital_to_commercial","fair_rbp_book","fair_rbp_price"]},{"source_id":"hospital_chargemaster_current","source_fqn":"vlada_curated.vw_fact_hospital_chargemaster_current","title":"Hospital chargemaster — current (full, wide) view","domain":"hospital","stage":"semantic_view","status":"live","grain":"One row per current chargemaster rate_id (full 93-column detail).","description":"The widest current-vintage hospital-chargemaster view (rate_id grain, ~93 cols incl alt-code arrays, all payer/plan/rate attributes). The full-detail surface for deep inspection / lineage; downstream views project from it.","identity_key":"rate_id","row_count":null,"last_updated":null,"freshness_sla":"Derived (current vintage).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Current-vintage view."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_fact_hospital_chargemaster_current","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Very wide (93 cols) — select only needed columns."],"notes":null,"tools":[]},{"source_id":"hospital_chargemaster_validated","source_fqn":"vlada_curated.vw_fact_hospital_chargemaster_validated","title":"Hospital chargemaster — validated view","domain":"hospital","stage":"semantic_view","status":"live","grain":"One row per validated hospital rate (rate_id).","description":"The validated hospital-chargemaster view: rates passing validation, with description, payer/plan, rate type, rate, gross charge. The quality-gated rate surface.","identity_key":"rate_id","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived view."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_fact_hospital_chargemaster_validated","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Validation gate may drop edge cases present in _canonical."],"notes":null,"tools":[]},{"source_id":"hospital_comparability_mat","source_fqn":"vlada_curated.fact_hospital_comparability_mat","title":"Hospital comparability materialized table (per-state)","domain":"hospital","stage":"mart","status":"live","grain":"One row per (CCN, billing_code, payer, plan, billing_class) with comparability class.","description":"The materialized table backing vw_fact_hospital_chargemaster_comparable — hospital rates with payer entity/plan structure + comparability_class precomputed per state. The physical mart the pricing live-fetcher reads.","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived (per-state build).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Per-state materialization."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_hospital_comparability_mat","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Built per-state; a partition gap = a missing state (see the HPT serving DQ lesson)."],"notes":null,"tools":[]},{"source_id":"hospital_mart_cell","source_fqn":"vlada_curated.mart_hospital_cell","title":"Hospital price-cell mart","domain":"hospital","stage":"mart","status":"live","grain":"One row per (CCN, billing_code, payer, plan, LOB, methodology, rate_type) price cell.","description":"The hospital price-cell serving mart — one materialized cell per (hospital, code, payer, plan, line_of_business, methodology, rate_type) with the rate. The precomputed serving grain for hospital price answers.","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived (incremental cell build).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Incremental cell build."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.mart_hospital_cell","commercial_terms":"Public HPT data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/hospital/chargemaster_serving_views.md","known_gaps":["Incremental mart; reads gated by VLADA_HPT_CELL_TABLE serving flag."],"notes":null,"tools":[]},{"source_id":"medicare_benchmark_view","source_fqn":"vlada_curated.vw_medicare_benchmark","title":"Medicare benchmark view (allowed by code × class)","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per (billing_code, billing_class) — Medicare allowed + source/year.","description":"A unified Medicare-allowed benchmark view by billing code + class, with the medicare_source (PFS/OPPS/etc.) and year. The single benchmark surface the RBP pricing router reads for \"Medicare allowed for this code\".","identity_key":"billing_code","row_count":null,"last_updated":null,"freshness_sla":"Derived (from the Medicare fee schedules).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived from the fee schedules."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_medicare_benchmark","commercial_terms":"Public CMS data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["National benchmark; for geographic detail use fact_*_payment_by_geo + localization."],"notes":null,"tools":["compare_hospital_to_commercial","county_expert","county_price_options","fair_rbp_book"]},{"source_id":"care_site_verification_fact","source_fqn":"vlada_curated.fact_care_site_verification","title":"Care-site verification (county-fleet promoted truth)","domain":"provider_identity","stage":"curated","status":"live","grain":"One row per (NPI, county, care_site_class) — verified care-site verdict.","description":"The county-fleet promoted verification table: per NPI/county/class, the fleet_status (verified/reclassified/duplicate/unresolved), canonical site id, parent system, true facility type, confidence. The audited truth of which care sites are real (vw_care_site_verified serves it enriched).","identity_key":"npi","row_count":null,"last_updated":null,"freshness_sla":"Derived (per county-fleet vintage).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Per county-fleet vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_care_site_verification","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Coverage = counties the fleet has run; absence = not-yet-verified, not invalid."],"notes":null,"tools":[]},{"source_id":"care_site_verified_view","source_fqn":"vlada_curated.vw_care_site_verified","title":"Care-site verified view (enriched)","domain":"provider_identity","stage":"semantic_view","status":"live","grain":"One row per verified care site (NPI) with identity + geography enrichment.","description":"Serving view unioning dim_care_site with fact_care_site_verification — verified care sites with legal name, CCN, class, county, parent system. The surface county_expert/county_intelligence read.","identity_key":"npi","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived view."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.vw_care_site_verified","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Honors the fleet's care_site_class; only verified sites surface."],"notes":null,"tools":[]},{"source_id":"care_site_geo","source_fqn":"vlada_curated.care_site_geo","title":"Care-site geography (CCN → CBSA/county/ZIP)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per care site (hospital_ccn) — its CBSA/county/ZIP geography.","description":"Care-site geography: hospital_ccn → care_site_type, CBSA, county FIPS, ZIP, city, state with geo source + vintage. Places each care site in its market.","identity_key":"hospital_ccn","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":"geo_vintage","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'geo_vintage' stamps the geocoding vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.care_site_geo","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["geo_source/geo_vintage record provenance; geocoding can be approximate."],"notes":null,"tools":[]},{"source_id":"agg_county_intelligence","source_fqn":"vlada_curated.agg_county_intelligence","title":"County intelligence aggregate (supply by class)","domain":"curated","stage":"mart","status":"live","grain":"One row per (county_fips, care_site_class) — verified site count + ownership/ccn flags.","description":"County-fleet serving aggregate: per county and care-site class, the verified site_count, tier, ownership_resolved and ccn_linked flags. Backs the county_intelligence / county_expert supply answers.","identity_key":"county_fips","row_count":null,"last_updated":null,"freshness_sla":"Derived (per county-fleet vintage).","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Per county-fleet vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_county_intelligence","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Counties present = fleet-run counties."],"notes":null,"tools":[]},{"source_id":"agg_care_site_payer_coverage","source_fqn":"vlada_curated.agg_care_site_payer_coverage","title":"Care-site × payer coverage aggregate","domain":"curated","stage":"mart","status":"live","grain":"One row per (NPI, care_site_class, county, payer) — coverage + rate/contract shape.","description":"Aggregate of which payers have rates for each care site: NPI × class × county × payer with resolved flag, provider_group_count, rate_count, contract_shape. Backs county payer-coverage answers + the pricing flywheel.","identity_key":"npi","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived aggregate."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_care_site_payer_coverage","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Coverage reflects extracted payers; absence != no contract."],"notes":null,"tools":["county_intelligence","county_price_options","state_expert"]},{"source_id":"agg_county_payer_landscape","source_fqn":"vlada_curated.agg_county_payer_landscape","title":"County × payer landscape aggregate","domain":"curated","stage":"mart","status":"live","grain":"One row per (county_fips, payer_id) — hospital MRF row count + status.","description":"Per county and payer, the hospital MRF coverage (hospital_mrf_rows) + status. A coverage map of which payers have hospital pricing in each county.","identity_key":"county_fips","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived aggregate."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_county_payer_landscape","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Coverage of extracted payers only."],"notes":null,"tools":[]},{"source_id":"agg_state_payer_roster","source_fqn":"vlada_curated.agg_state_payer_roster","title":"State × payer roster aggregate","domain":"curated","stage":"mart","status":"live","grain":"One row per (state, payer_id) — coverage + build/action status.","description":"Per state and payer, coverage counts (ct_hospitals, mrf_rows), in_rds/built flags, and a recommended action. The operator-facing roster of payer coverage + what to build next per state.","identity_key":"state","row_count":null,"last_updated":null,"freshness_sla":"Derived.","recollection":{"cadence":"derived","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Derived aggregate."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_state_payer_roster","commercial_terms":"Derived from public data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/county_care_site_fleet.md","known_gaps":["Operator/work-queue aggregate; 'action' is advisory."],"notes":null,"tools":[]},{"source_id":"policy_document","source_fqn":"vlada_curated.fact_policy_document","title":"Policy document corpus (state/federal regulation docs)","domain":"curated","stage":"curated","status":"live","grain":"One row per policy document (doc_id) — title, citation, authority, S3 refs.","description":"The document-grounded policy corpus: per regulation document, title, citation, authority, format, size, status, and S3 raw/text pointers. The foundation that grounds state/federal effective-policy claims in cited docs.","identity_key":"doc_id","row_count":null,"last_updated":null,"freshness_sla":"Event-driven (as policy docs are ingested).","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' stamps when the document was ingested."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_policy_document","commercial_terms":"Public regulation text.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/policy_corpus.md","known_gaps":["Coverage = ingested states/agencies; chunks for retrieval live in fact_policy_doc_chunk."],"notes":null,"tools":[]},{"source_id":"policy_doc_chunk","source_fqn":"vlada_curated.fact_policy_doc_chunk","title":"Policy document chunks (retrieval units with citations)","domain":"curated","stage":"curated","status":"live","grain":"One row per (doc_id, chunk_no) — a citation-anchored text chunk.","description":"Chunked policy text for retrieval: doc_id, chunk_no, anchor, citation, text. The retrieval grain for document-grounded policy answers (every claim ties to a cited chunk).","identity_key":"doc_id","row_count":null,"last_updated":null,"freshness_sla":"Event-driven (with the document corpus).","recollection":{"cadence":"event_driven","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' stamps ingestion of the parent document."]},"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_policy_doc_chunk","commercial_terms":"Public regulation text.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/curated/policy_corpus.md","known_gaps":["Chunking is for retrieval; cite via the anchor/citation, not chunk_no."],"notes":null,"tools":[]},{"source_id":"medicare_landscape_ma_all","source_fqn":"medicare_silver.landscape_ma_all","title":"Medicare Advantage Landscape (plans by county × year)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (report_year, contract, plan, segment, county) — MA plan + premiums.","description":"The CMS MA Landscape file — every MA/Part D plan offered by county and year with org/plan name, plan type, and premiums (consolidated, Part C, Part D). The plan-availability + premium spine for MA market analysis.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"Annual (CMS Landscape, AEP).","recollection":{"cadence":"annual","watermark_field":"report_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.landscape_ma_all","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_landscape.md","known_gaps":["Plan availability + premium only; benefits detail is in the PBP tables."],"notes":null,"tools":[]},{"source_id":"medicare_mpf_optional_supplemental","source_fqn":"medicare_silver.mpf_optional_supplemental_annual","title":"Medicare Plan Finder — optional supplemental benefits (annual)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (contract, plan, segment, package, service category, year) — supplemental benefit + cost share.","description":"Medicare Plan Finder optional supplemental benefit packages by plan and year: package, service category, whether offered, cost-share type and amount. The optional-supplemental benefit detail layer for MA plans.","identity_key":"contract_id","row_count":null,"last_updated":null,"freshness_sla":"Annual.","recollection":{"cadence":"annual","watermark_field":"contract_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'contract_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mpf_optional_supplemental_annual","commercial_terms":"Public CMS data.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/ma_landscape.md","known_gaps":["Optional supplemental packages only; mandatory benefits are in PBP. Null cost_share != $0 — see PBP semantics."],"notes":null,"tools":[]},{"source_id":"fda_drug_master_file","source_fqn":"drug_silver.dim_dmf","title":"FDA Drug Master Files (DMF)","domain":"drug","stage":"dim","status":"live","grain":"One row per Drug Master File (dmf_number) — type, status, holder, subject.","description":"FDA Drug Master Files — confidential filings (type, status, holder, subject, submit date) referenced by drug applications. Supply-chain / API-source reference for a drug.","identity_key":"dmf_number","row_count":450360,"last_updated":"2026-07-11","freshness_sla":"Quarterly (FDA DMF list).","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_dmf","commercial_terms":"Public FDA data.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["DMF contents are confidential; only the index metadata is public.","Loaded/proven XLSX-era snapshots for 2020 and 2022-2025: 10 asserted dates and 369,630 loaded rows; live table 450,360 rows / 12 periods. Current-list consumers must filter asserted_at = max(asserted_at), not is_current.","49 artifacts / 122,351,228 bytes including the manifest are byte-secured and SHA-256 pinned under s3://vlada-platform-raw/drug/bronze/fda_dmf_archive/; manifest: s3://vlada-platform-raw/drug/bronze/fda_dmf_archive/acquisition_manifest_2026-07-11.json.","Exact deferred gate: accept WPD, fixed-format text, OLE2 XLS, and media-era XLSX/text parser adapters; content-sniff and canonicalize the 26 fixed-ID captures by quarter; preserve DMF number + holder + subject + type + status per vintage with cumulative-list replace by observed_period; and prove per-item URL/bytes/SHA, dry-run, duplicate-key, and idempotency.","Proven limits: 1Q2019 publication gap; 4Q2019 crawl gap; 3Q2018 crawl gap; 1999 3Q file 404ed twice; 1997 4000to5999.wpd absent; combined 0to12491.wpd only a 301; 3Q2000 and 4Q2003 missing; 2Q2007 replaced by 1.5Q2007; 2Q2019 truncated at 1,048,576 bytes versus 2,557,077 original bytes and excluded.","Hard consumer guard: historical DMF vintages must not flow into vlada/tools/supply_chain_concentration_risk.py:144 until the deferred semantics gate is accepted."],"notes":"Loaded/proven XLSX-era DMF state remains served unchanged; residual history is byte-secured in an exact deferred lane.","tools":[]},{"source_id":"drug_clinical_trial","source_fqn":"drug_silver.fact_drug_clinical_trial","title":"Clinical Trials (ClinicalTrials.gov, drug-regulated)","domain":"drug","stage":"silver","status":"live","grain":"One row per trial (nct_id, data_year) — status, phase, sponsor, enrollment.","description":"ClinicalTrials.gov records (drug-regulated): NCT id, title, overall status, study type, phase, enrollment, lead sponsor + class, FDA-regulated flag, has_results. The pipeline/evidence context for a drug.","identity_key":"nct_id","row_count":null,"last_updated":null,"freshness_sla":"Periodic (ClinicalTrials.gov).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_clinical_trial","commercial_terms":"Public NLM data.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/drug_reference_rxclass_orangebook.md","known_gaps":["Drug-regulated subset; link to a drug via sponsor/intervention (no clean NDC)."],"notes":null,"tools":[]},{"source_id":"form5500_service_provider_code","source_fqn":"drug_silver.fact_form5500_service_provider_code","title":"Form 5500 — service provider codes (Schedule C)","domain":"drug","stage":"silver","status":"live","grain":"One row per (filing ack_id, plan_year, service code) — provider service code; served plan years 2009-2025. Pre-EFAST2 1999-2008 is secured but deferred to a separate legacy table family.","description":"The EFAST2 Form 5500 Schedule C service-provider service codes per filing for plan years 2009-2025. The pre-EFAST2 Schedule C archive is byte-secured but is not merged into this certified EFAST2 sidecar.","identity_key":"ack_id","row_count":10554124,"last_updated":"2026-07-11","freshness_sla":"Annual (DOL Form 5500).","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage/currency column.","freshness_threshold, expected_delta, and stale_behavior are intentionally null: not pinned in source docs, and a fresh-vs-stale verdict needs a live watermark read this catalog never performs.","The served sidecar joins to the served provider rows by ack_id; pre-EFAST2 remains in the separate deferred legacy lane."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_form5500_service_provider_code","commercial_terms":"Public DOL data.","provenance_chain_ref":"drug_silver M-2 substrate","context_doc_path":"docs/context_library/drug/form5500_schedule_c.md","known_gaps":["EFAST2 2009-2025 is loaded/proven at 10,554,124 service-code rows; the three-table EFAST2 family totals 13,037,746 rows.","Pre-EFAST2 1999-2008 bytes are secured in 160 files totaling 1,973,997,290 bytes with zero misses and the full SHA-256/S3 manifest, but legacy code serving is intentionally deferred.","Pre-2009 service-code semantics belong to the separate FILING_ID-keyed legacy table family; do not join them to ACK_ID or union them into the EFAST2 sidecar."],"notes":"Terminal state complete_and_served for the EFAST2 era with a documented pre-EFAST2 source limit; archive manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/form5500.json.","tools":[]},{"source_id":"cms_provider_ownership","source_fqn":"medicare_silver.fact_provider_ownership","title":"CMS PECOS Provider Ownership (\"All Owners\", PE-rollup layer)","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per facility ↔ owner edge (enrollment_id × owner), partitioned by facility_type.","description":"The CMS PECOS \"All Owners\" ownership records, unified across six facility types (hospital, hha, hospice, snf, fqhc, rhc). One row per facility↔owner edge: owner identity (individual or org name/DBA/address), percentage ownership, role, association date, and the owner-type flags that drive accountability/PE analysis — PRIVATE EQUITY, REIT, HOLDING COMPANY, INVESTMENT FIRM, CHAIN HOME OFFICE, PARENT COMPANY, TRUST/TRUSTEE, FOR/NON PROFIT, plus an indirect-chain \"owned by another org\" flag. THE ownership / private-equity-rollup intelligence layer (who really owns each facility).","identity_key":"enrollment_id","row_count":814242,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes the PECOS ownership files (~monthly).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp; CMS refreshes the PECOS ownership files roughly monthly."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_provider_ownership","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/provider_ownership.md","known_gaps":["row_count ~814,242 across types (hospital 147,332 / hha 101,100 / hospice 71,133 / snf 280,207 / fqhc 148,919 / rhc 65,551, 2026-05 files).","Owner→facility link is the enrollment_id/associate_id (PECOS), not the CCN/NPI directly; bridge via PECOS enrollment to reach CCN/NPI.","PARENT COMPANY / TRUST-OR-TRUSTEE flags are present on SNF (and later types); null where the source file lacks the column (other facility types).","Owner identity is self-reported on the PECOS enrollment; percentage_ownership can be null for indirect interests."],"notes":"Iceberg table medicare_silver.fact_provider_ownership, partitioned by facility_type; one All-Owners file fully restates its type (replace, idempotent by SHA-256). One runner ingests all six datasets.","tools":[]},{"source_id":"cms_hospital_service_area","source_fqn":"medicare_silver.fact_hospital_service_area","title":"CMS Hospital Service Area (referral geography by CCN × ZIP)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (data_year, hospital CCN, patient ZIP) — cases/days/charges.","description":"The CMS Hospital Service Area file — for each hospital (CCN) the ZIP codes its Medicare FFS patients reside in, with total_cases, total_days_of_care, total_charges. The referral-GEOGRAPHY layer: which markets a hospital draws from, and (inverted) which hospitals serve a ZIP / compete in a market. Multi-year (2015–2024), partitioned by data_year.","identity_key":"ccn","row_count":1155777,"last_updated":null,"freshness_sla":"Annual (CMS Hospital Service Area release).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospital_service_area","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/hospital/hospital_service_area.md","known_gaps":["row_count is per latest year (2024 ~1.16M); 10 years loaded (2015–2024), partition by data_year.","Medicare FFS only (no MA/commercial); CMS redacts small cells (<11 cases) — those rows are absent.","Patient geography is ZIP of residence; join to dim_geography for county/CBSA rollups."],"notes":"Iceberg table medicare_silver.fact_hospital_service_area, partitioned by data_year (replace per year, idempotent by SHA-256).","tools":[]},{"source_id":"cms_medicare_geo_variation","source_fqn":"medicare_silver.fact_medicare_geo_variation","title":"CMS Medicare Geographic Variation (per-capita cost + utilization by geography)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (year, bene_geo_level, bene_geo_code, bene_age_level) — National/State/County.","description":"The CMS Medicare Geographic Variation PUF — Medicare FFS standardized per-capita cost and utilization by geography and year (National / State / County), curated to the high-value subset: population + demographics, total standardized per-capita payment, per-service-category standardized per-capita cost (IP, OP, ASC, SNF, HH, hospice, E&M, procedures, tests, imaging, DME, FQHC/RHC, ambulance), and key utilization (IP stays /1,000, readmission %, ER visits /1,000, imaging events /1,000). THE medical geographic-variation benchmark — how Medicare spend per beneficiary varies by market (the cost counterpart to the drug geo-variation we already had).","identity_key":"bene_geo_code","row_count":37000,"last_updated":null,"freshness_sla":"Annual (CMS Geographic Variation PUF).","recollection":{"cadence":"annual","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_medicare_geo_variation","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/medicare_geo_variation.md","known_gaps":["~37k rows = 11 years (2014-2024) x (3 National + 165 State + ~3,194 County age-levels), partition by year.","CURATED PROJECTION of the 246-col PUF (kept ~33 high-value metrics; full PUF at the source URL). Standardized per-capita = wage/geography-adjusted, the comparable benchmark.","County is the finest CMS-published CSV grain; the Hospital-Referral-Region (HRR) file has NO CSV distribution (viz-only) and is therefore not ingestible.","Medicare FFS only (MA excluded from the spend metrics); bene_age_level splits All/<65/65+."],"notes":"Iceberg table medicare_silver.fact_medicare_geo_variation, partitioned by year (replace per year, single source file with an in-row YEAR column).","tools":[]},{"source_id":"cms_hrrp","source_fqn":"medicare_silver.fact_hrrp","title":"CMS Hospital Readmissions Reduction Program (HRRP)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (fiscal_year, ccn, measure_name) — full HRRP program history FY2013-FY2026","description":"The CMS Hospital Readmissions Reduction Program file — per hospital CCN, fiscal year, and condition measure, carrying excess readmission ratio, predicted and expected readmission rates, discharges, and readmissions.","identity_key":"fiscal_year,ccn,measure_name","row_count":245914,"last_updated":"2026-07-11","freshness_sla":"Annual HRRP fiscal-year refresh.","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Serve current penalties from max(fiscal_year); historical analysis filters explicit fiscal_year.","Suppressed Too Few to Report/N/A values remain null per parser policy."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hrrp","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; source_url and sha256_content_hash are populated for every loaded row.","context_doc_path":"docs/context_library/hospital/hospital_programs_hrrp_hvbp.md","known_gaps":["Suppressed Too Few to Report/N/A values are null per parser policy, not $0.","observed_period uses the 2026-06-27 acquisition date for FY2026 while FY vintages use date(fiscal_year-1,10,1) anchors; preserve the mixed convention.","Current serving pins max(fiscal_year); historical analysis must filter explicit fiscal_year.","Measure-set drift is source history: FY2013-FY2014 have AMI/HF/PN; FY2015-FY2016 add COPD and THA/TKA; FY2017-FY2026 have six measures including CABG."],"notes":"Iceberg medicare_silver.fact_hrrp, partition by fiscal_year with FY-scoped replace semantics. Natural key is (fiscal_year,ccn,measure_name); registry ids are cms_hrrp#fy<year>.","tools":[]},{"source_id":"cms_hvbp","source_fqn":"medicare_silver.fact_hvbp","title":"CMS Hospital Value-Based Purchasing (HVBP) Total Performance Score","domain":"hospital","stage":"silver","status":"live","grain":"One row per (fiscal_year, hospital CCN) — domain scores + total performance score.","description":"The CMS Hospital Value-Based Purchasing Total Performance Score file — per hospital and fiscal year the four domain scores (Clinical Outcomes, Person & Community Engagement, Safety, Efficiency & Cost Reduction; unweighted + weighted) and the overall Total Performance Score that drives the VBP payment adjustment. The value-based-purchasing accountability layer.","identity_key":"ccn","row_count":2455,"last_updated":null,"freshness_sla":"Annual (HVBP fiscal year).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hvbp","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/hospital/hospital_programs_hrrp_hvbp.md","known_gaps":["~2,455 hospitals (FY2026); only hospitals meeting minimums get a Total Performance Score (others null).","Partitioned by fiscal_year; weighted domain scores roll into the TPS."],"notes":"Iceberg medicare_silver.fact_hvbp, partition by fiscal_year, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_esrd_qip","source_fqn":"medicare_silver.fact_esrd_qip","title":"CMS ESRD QIP Total Performance Score (dialysis pay-for-performance)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (payment_year, dialysis facility CCN) — TPS + payment reduction.","description":"The CMS ESRD Quality Incentive Program Total Performance Score — per dialysis facility the Total Performance Score vs state and national averages, and the resulting payment_reduction_pct (0–2%). The dialysis pay-for-performance / penalty layer (the dialysis counterpart to HVBP/HRRP for hospitals).","identity_key":"ccn","row_count":7558,"last_updated":null,"freshness_sla":"Annual (ESRD QIP payment year).","recollection":{"cadence":"annual","watermark_field":"payment_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'payment_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_esrd_qip","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/dialysis_quality.md","known_gaps":["~7,558 facilities (Payment Year 2026); only the latest payment year is loaded (partition by payment_year).","payment_reduction_pct > 0 = penalized; join CCN to dim_dialysis_facility (roster) + dim_dialysis_facility_quality (five-star)."],"notes":"Iceberg medicare_silver.fact_esrd_qip, partition by payment_year, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_dialysis_facility_quality","source_fqn":"medicare_silver.dim_dialysis_facility_quality","title":"CMS Dialysis Facility quality (five-star + facility attributes)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per dialysis facility CCN — five-star rating + ownership/services/mortality.","description":"Curated subset of the CMS Dialysis Facility Listing (142-col): five-star rating, profit/non-profit, chain owned + chain organization, number of dialysis stations, services offered (in-center HD / peritoneal / home HD training), and facility mortality rate. The dialysis facility quality + attribute enrichment (complements the dim_dialysis_facility roster + the ESRD QIP performance score).","identity_key":"ccn","row_count":7557,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes the Dialysis Facility listing.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (current listing snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_dialysis_facility_quality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/dialysis_quality.md","known_gaps":["CURATED PROJECTION of the 142-col listing (~15 high-value cols; full listing has many more clinical measures).","five_star null for facilities without a rating (~485 of 7,557); partition by state."],"notes":"Iceberg medicare_silver.dim_dialysis_facility_quality, partition by state, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_pecos_enrollment","source_fqn":"medicare_silver.fact_pecos_enrollment","title":"CMS Medicare FFS Public Provider Enrollment (PECOS NPI↔enrollment bridge)","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per Medicare enrollment (enrollment_id) — NPI + associate_id + provider type.","description":"The CMS Medicare Fee-For-Service Public Provider Enrollment registry — one row per PECOS enrollment linking NPI ↔ enrollment_id (ENRLMT_ID) ↔ associate_id (PECOS_ASCT_CNTL_ID), with provider type and name. THE bridge that resolves fact_provider_ownership (keyed on enrollment_id / owner_associate_id) to a provider NPI — closing the ownership→NPI gap. ~2.98M enrollments / 2.56M NPIs.","identity_key":"npi","row_count":2981799,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes the public enrollment file (~quarterly).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (current snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_pecos_enrollment","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/pecos_enrollment.md","known_gaps":["~2.98M enrollments; an NPI can have multiple enrollments (multiple_npi_flag) — join carefully.","Carries NPI + associate_id, not CCN directly; CCN comes via the per-type Enrollments files (future) or dim_hospital_external."],"notes":"Iceberg medicare_silver.fact_pecos_enrollment, partition by state, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_facility_npi_ccn_xref","source_fqn":"medicare_silver.facility_npi_ccn_xref","title":"CMS Facility Organization NPI to CCN Crosswalk","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per exact CMS-published facility organization NPI to Medicare CCN edge, by facility type and source file.","description":"Exact facility NPI<->CCN bridge derived from CMS per-provider-type Public Provider Enrollment files: Home Health Agency Enrollments, Hospice Enrollments, Skilled Nursing Facility Enrollments, Rural Health Clinic Enrollments, and Federally Qualified Health Center Enrollments. Each source row carries both NPI and CCN; the pipeline emits direct edges only, with no fuzzy matching, name similarity, or address matching.","identity_key":"npi","row_count":null,"last_updated":null,"freshness_sla":"Refreshed when CMS republishes per-type enrollment files (generally monthly/quarterly by file).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (current snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.facility_npi_ccn_xref","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/facility_npi_ccn_xref.md","known_gaps":["Current-snapshot enrollment files only; no historical NPI<->CCN intervals.","Multi-CCN NPIs can exist; FacilityCcnResolver treats those NPIs as ambiguous and falls back to exact name+ZIP/state only when available.","Covers HHA, hospice, SNF, RHC, and FQHC per-type enrollment files. ESRD/dialysis already resolves through vlada_curated.dim_dialysis_facility."],"notes":"Iceberg table medicare_silver.facility_npi_ccn_xref, partitioned by facility_type; one atomic per-facility-type replace per ingest. Source rows are exact CMS-published enrollment edges.","tools":[]},{"source_id":"cms_ncci_ptp","source_fqn":"medicare_silver.ncci_ptp","title":"CMS NCCI Procedure-to-Procedure (PTP) Edits — Practitioner","domain":"medicare","stage":"silver","status":"live","grain":"One row per active CMS NCCI PTP edit pair (Column-1 comprehensive code, Column-2 component code) with its modifier indicator and setting.","description":"CMS National Correct Coding Initiative Procedure-to-Procedure edits: pairs of HCPCS/CPT codes that are NOT separately payable when billed together for the same patient on the same date. Each edit names a Column-1 (comprehensive) code and the Column-2 (component) code bundled into it, plus a modifier indicator (0=never bypassable; 1/9=a distinct-procedure modifier such as 59/XE/XS/XP/XU can separate the pair). Used by the claims-repricing engine to bundle component lines so professional (and outpatient) claims are not double-counted. Quarterly CMS file (2026 Q3, ccipra v322r0); active edits only.","identity_key":"column_1_code","row_count":1728585,"last_updated":null,"freshness_sla":"Refreshed quarterly when CMS republishes the NCCI edit files.","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (current snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ncci_ptp","commercial_terms":"Public CMS data (contains AMA CPT code identifiers); freely downloadable from cms.gov.","provenance_chain_ref":"CMS NCCI Practitioner PTP quarterly ZIP (ccipra-v322r0), parsed active edits; asserted_at stamped at load.","context_doc_path":"docs/context_library/medicare/ncci_ptp.md","known_gaps":["Practitioner setting only; Hospital/Outpatient (facility) PTP edits not yet loaded.","Current-snapshot active edits (deletion date '*'); historical/deleted edit intervals not retained.","MUE (Medically Unlikely Edits) not yet loaded (the engine does not unit-scale the Medicare leg today)."],"notes":"Iceberg table medicare_silver.ncci_ptp. Loaded from the CMS 2026 Q3 Practitioner PTP 4-part text export (>2.6M rows) deduped to 1,728,585 active unique pairs. The pricer queries it per-book (edits among present codes only), not a full in-memory load.","tools":[]},{"source_id":"cms_pfs_indicators","source_fqn":"medicare_silver.medicare_pfs_indicators","title":"CMS PFS Payment-Policy Indicators (PPRRVU)","domain":"medicare","stage":"silver","status":"live","grain":"One row per HCPCS x modifier from the CMS PFS Relative Value File — the status / global / PC-TC / multiple-procedure / bilateral indicators.","description":"Per HCPCS x modifier, the payment-policy indicators from the CMS PFS Relative Value File (PPRRVU) that the National Physician Fee Schedule pricing files drop: status_code (A/B/N/X...), global_period (000/010/090/XXX...), pctc_ind (PC/TC split), mult_proc_ind (the multiple-procedure reduction rule: 2=standard surgical MPPR 100/50/50, 3=endoscopy, 4=imaging, 5=therapy, 9=n/a), and bilat_ind (the bilateral rule: 1=150% adjustment applies). Used by the claims-repricing engine to apply the multiple-procedure reduction and bilateral adjustment so professional claims aren't paid in full where Medicare reduces. Quarterly CMS release (2026, rvu26c).","identity_key":"hcpcs","row_count":19356,"last_updated":null,"freshness_sla":"Refreshed when CMS posts a new quarterly PFS Relative Value File.","recollection":{"cadence":"quarterly","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (current snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_pfs_indicators","commercial_terms":"Public CMS data (references AMA CPT code identifiers); freely downloadable from cms.gov.","provenance_chain_ref":"pipelines/medicare/ingest/pfs_indicators_runner.py — PPRRVU CSV parsed positionally, M-2 envelope (asserted_at + sha256 + source_url) on every row.","context_doc_path":"docs/context_library/medicare/pfs_indicators.md","known_gaps":["Current-snapshot indicators (latest release); historical indicator changes not retained beyond the partition year.","Carries the policy indicators only (status/global/pctc/mult-proc/bilateral); the RVUs/conversion factor live in medicare_physician_fee_schedule."],"notes":"Iceberg table medicare_silver.medicare_pfs_indicators, partitioned by year. Parsed by stable PPRRVU column position (the multi-row header has ambiguous names). The pricer queries it per-book (codes present only).","tools":[]},{"source_id":"cms_physician_by_provider_service","source_fqn":"medicare_silver.fact_physician_by_provider_service","title":"Medicare Physician & Other Practitioners — by Provider and Service (granular price)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, rendering NPI, HCPCS, place of service) — charge/allowed/paid.","description":"The CMS Medicare Physician & Other Practitioners PUF at the **provider×service** grain: per rendering NPI, HCPCS, and place of service, the average submitted charge, **Medicare allowed**, Medicare paid, and standardized amounts, plus beneficiary/service counts. The GRANULAR per-provider price — the provider-level counterpart to the geo benchmark (`fact_physician_payment_by_geo`). ~9.8M rows/year, partitioned by data_year (2013-2024 available).","identity_key":"rndrng_npi","row_count":116297407,"last_updated":null,"freshness_sla":"Annual (CMS Physician & Other Practitioners PUF).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_physician_by_provider_service","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/physician_by_provider.md","known_gaps":["~9.8M rows PER YEAR; ALWAYS filter data_year (+ ideally state/HCPCS) — full scans are very expensive.","CURATED ~21-col subset of the 28-col PUF (kept identity + geo + the 4 value amounts + 3 counts; dropped street address / MI / RUCA desc).","HEAVY COMPUTE: future annual refresh/replay runs on the worker fleet (job_type build_physician_by_provider), not a laptop. Full 2013-2024 history is live/proven in Iceberg at 116,297,407 rows.","avg_medicare_standardized is wage/geography-adjusted (comparable across markets); avg_submitted_charge is billed, not paid."],"notes":"Iceberg medicare_silver.fact_physician_by_provider_service, partition by data_year; bulk-load (append_buffered per 500k-row chunk → flush_buffered_replace_partitions per year, atomic, idempotent by SHA-256).","tools":[]},{"source_id":"cms_inpatient_by_provider_service","source_fqn":"medicare_silver.fact_inpatient_by_provider_service","title":"Medicare Inpatient Hospitals — by Provider and Service (granular DRG price)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, hospital CCN, MS-DRG) — discharges + charge + payments.","description":"The CMS Medicare Inpatient Hospitals PUF at the provider×DRG grain: per hospital (CCN) and MS-DRG, total discharges, average submitted covered charge, average total payment, and average Medicare payment. The granular per-hospital inpatient price (provider-level counterpart to fact_inpatient_payment_by_geo). FY2011-FY2024 are loaded; FY2011-FY2013 are the CMS top-100-DRG era, while FY2014+ are broader all-DRG files.","identity_key":"ccn","row_count":2451944,"last_updated":null,"freshness_sla":"Annual (CMS Inpatient PUF).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_inpatient_by_provider_service","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/hospital_by_provider.md","known_gaps":["FY2011-FY2013 are CMS top-100 most frequently billed MS-DRG era files; FY2014+ are broader all-DRG files.","Curated subset (CCN/geo + DRG + discharges + 3 payment amounts; dropped street/city/RUCA-desc).","avg_submitted_charge is billed; avg_medicare_payment is what Medicare paid; avg_total_payment includes other payers' share."],"notes":"Iceberg medicare_silver.fact_inpatient_by_provider_service, partition by data_year, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_outpatient_by_provider_service","source_fqn":"medicare_silver.fact_outpatient_by_provider_service","title":"Medicare Outpatient Hospitals — by Provider and Service (granular APC price)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, hospital CCN, APC) — bene/services + charge + Medicare allowed/paid + outlier.","description":"The CMS Medicare Outpatient Hospitals PUF at the provider×APC grain: per hospital (CCN) and comprehensive APC, beneficiary/service counts plus average submitted charge, Medicare allowed, Medicare paid, and outlier amounts. The complete official C-APC series is loaded for 2015-2024 at 1,008,975 rows. This is a claims-derived provider benchmark, not the contractual OPPS fee schedule.","identity_key":"ccn","row_count":1008975,"last_updated":null,"freshness_sla":"Annual (CMS Outpatient PUF).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_outpatient_by_provider_service","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/hospital_by_provider.md","known_gaps":["CMS states that the current C-APC series begins in 2015; the incompatible pre-2015 predecessor PUF is not a missing vintage of this series.","Curated subset (CCN/geo + APC + counts + allowed/paid + outlier; dropped street/city/RUCA-desc).","APC grain, not HCPCS. The amount fields are claims-derived averages and are not the statutory OPPS payment-rate table.","Upstream CMS-value anomaly guardrail: 9 rows have capc_services >= 10,000; 4 have >=100 services per populated beneficiary and 7 pair >=10,000 services with avg_medicare_allowed < $100. Review/quarantine these rows before volume-weighted analysis.","CCN joins require a unique partner row. The 2026-07-10 overlap audit found 2024 coverage of 97.31% to care_site_geo and 98.59% to dim_hospital_external, but care_site_geo has 76 multi-row CCNs and can fan out unless deduplicated."],"notes":"Iceberg medicare_silver.fact_outpatient_by_provider_service, partition by data_year, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_dme_by_supplier_service","source_fqn":"medicare_silver.fact_dme_by_supplier_service","title":"Medicare DME, Devices & Supplies — by Supplier and Service (granular supplier price)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, supplier NPI, HCPCS) — charge/allowed/paid/standardized.","description":"The CMS Medicare DME PUF at the supplier×HCPCS grain: per supplier NPI and HCPCS, the avg submitted charge, Medicare allowed, paid, and standardized amounts + bene/claim/service counts, with RBCS clinical category, specialty, and rental indicator. The granular per-supplier DME price (provider-level counterpart to fact_dme_payment_by_geo). ~464k rows/year, 2014-2023, partition by data_year.","identity_key":"suplr_npi","row_count":463784,"last_updated":null,"freshness_sla":"Annual (CMS DME PUF).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_dme_by_supplier_service","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/dme_and_clfs_private.md","known_gaps":["~464k rows/year (2014-2023); curated subset (supplier/geo + specialty + RBCS + HCPCS + rental + counts + 4 amounts; dropped street/MI/credentials).","suplr_rentl_ind flags rented vs purchased; avg_medicare_standardized is geography-adjusted."],"notes":"Iceberg medicare_silver.fact_dme_by_supplier_service, partition by data_year, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_clfs_private_payer_rate","source_fqn":"medicare_silver.fact_clfs_private_payer_rate","title":"Medicare CLFS Private Payer Rates and Volumes (PAMA)","domain":"medicare","stage":"silver","status":"live","grain":"One row per reported (collection_year, row_seq) private-payer rate/volume observation, keyed to HCPCS.","description":"The PAMA \"applicable information\" — private-payer rates and volumes labs report to CMS, per HCPCS. A RARE public private-rate signal (distinct from the standard CLFS fee schedule `medicare_clfs`). The CMS-computed weighted median of these sets the CLFS; this is the underlying per-observation distribution.","identity_key":"hcpcs_cd","row_count":967129,"last_updated":null,"freshness_sla":"Per PAMA data-collection cycle (every 3 years).","recollection":{"cadence":"derived","watermark_field":"collection_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'collection_year' is the PAMA data-collection cycle year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_clfs_private_payer_rate","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/dme_and_clfs_private.md","known_gaps":["RAW per-observation rows (~967k, collection year 2018) — many rows per HCPCS; aggregate (e.g. weighted median) per hcpcs_cd for a single benchmark.","volume_text is a text field (may be ranges); private_payer_rate is the reported rate amount."],"notes":"Iceberg medicare_silver.fact_clfs_private_payer_rate, partition by collection_year, replace (idempotent by SHA-256). row_seq makes each observation unique.","tools":[]},{"source_id":"cms_market_saturation","source_fqn":"medicare_silver.fact_market_saturation","title":"CMS Market Saturation & Utilization (provider competition by county × service)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (reference_period, type_of_service, aggregation_level, state_fips, county_fips) — providers/users/payment.","description":"The CMS Market Saturation & Utilization file — per rolling reference period, service type, and county: number of FFS beneficiaries, number of providers, number of users, average users-per-provider, average providers-per-county, dual-eligible user counts/percentages, and total payment. The provider COMPETITION / market-concentration signal (high providers-per-county = saturated; used to flag over/under-supply). Curated subset of the dashboard file (drops *_dual_color / *_description / *_change rendering columns).","identity_key":"county_fips","row_count":2455330,"last_updated":null,"freshness_sla":"Quarterly rolling 12-month windows through Release 16; annual updates starting with Release 17 in 2024.","recollection":{"cadence":"annual","watermark_field":"reference_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'reference_period' is the source's rolling-window vintage; publication was quarterly through Release 16 and is annual from Release 17 (2024)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_market_saturation","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/market_saturation.md","known_gaps":["Full official history is loaded: 2,455,330 rows across 36 reference periods from 2014-10-01/2015-09-30 through CY2025, with two source hashes and zero natural-key duplicates.","aggregation_level splits national, state, and county rows; filter to one before comparing. Covers 24 selected FFS service categories, not all Medicare services.","County geography is a composite key: concatenate two-digit state_fips + three-digit county_fips. county_fips alone has zero overlap with the five-digit dim_geography key.","The composite county key overlaps 99.14% of dim_geography counties; the 27 unmatched values are 9 Connecticut planning regions and 18 Virginia independent cities. Deduplicate dim_geography from ZIP grain to one row per county before joining.","National/state maxima are legitimate aggregate scale, not parser corruption; hold aggregation_level, reference_period, and type_of_service constant."],"notes":"Iceberg medicare_silver.fact_market_saturation, partition by reference_period, replace (idempotent by SHA-256).","tools":[]},{"source_id":"cms_provider_of_services","source_fqn":"medicare_silver.fact_provider_of_services","title":"CMS Provider of Services (POS) File — facility characteristics + bed counts","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per (data_year, facility CCN) — category, control type, location, beds, status.","description":"The CMS Provider of Services File (QIES extract) — facility characteristics for every Medicare-certified facility: provider category + subtype, ownership control type, address/CBSA/FIPS location, certification + original participation + termination dates, and BED COUNTS (total, certified, Medicare SNF, hospice, rehab, psych/rehab unit) + affiliated-facility counts (HHA/SNF/hospice). The facility-structure layer (beds, ownership type, certification status) joinable by CCN. Curated ~30-col subset of the 473-col POS file, 2011-2026, partition by data_year.","identity_key":"prvdr_num","row_count":2086719,"last_updated":null,"freshness_sla":"Annual (CMS POS File).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_provider_of_services","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/provider_of_services.md","known_gaps":["~44k facilities/year (QIES extract; not the separate Clinical-Labs POS file); 16 years (2011-2026), partition by data_year.","CURATED ~30-col subset of 473 (identity/location/status/control-type + bed counts + key affiliated counts; full POS has many more service-availability switches at the source URL).","control_type_cd + provider_category_cd are CMS code values (decode via the POS data dictionary).","2011-2026 is evidence-complete and served unchanged: 2,086,719 rows across 16 years, 16 URLs, 16 hashes, zero lineage-null rows, and zero duplicate (data_year, prvdr_num) groups.","NBER 1984-2010 is an evidence-complete exact gate: approve access, run the bounded three-era repeatability test (1984-1996, 1997-2010, 2011 boundary), then accept the crosswalk/CLIA policy, per-year URL/SHA manifest, fail-closed adapter, and proofed replay."],"notes":"Iceberg medicare_silver.fact_provider_of_services, partition by data_year, replace (idempotent by SHA-256); current consumers must provide data_year, and is_current is not a cross-year latest selector.","tools":[]},{"source_id":"cms_post_acute_utilization","source_fqn":"medicare_silver.fact_post_acute_utilization","title":"Medicare Post-Acute Care Utilization — by Provider (SNF/HHA/Hospice/IRF/LTCH)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (setting, year, provider, summary/service category) — episodes/days/charge/allowed/payment.","description":"The CMS Medicare Post-Acute Care Utilization PUFs, unified across the five post-acute settings (SNF, HHA, hospice, IRF, LTCH) into one fact partitioned by (setting, year). Per provider: distinct beneficiaries, episodes/stays, service days, total charge, total allowed, total Medicare payment + standardized payment, plus beneficiary mix (dual %, rural %, avg age, avg risk score). The provider-level post-acute utilization + cost layer — completes provider-level coverage alongside physician / inpatient / outpatient / DME by provider.","identity_key":"prvdr_id","row_count":14214,"last_updated":null,"freshness_sla":"Annual (CMS Post-Acute Care Utilization PUFs).","recollection":{"cadence":"annual","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_post_acute_utilization","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/medicare/post_acute_utilization.md","known_gaps":["row_count is per setting-year (e.g. SNF 2023 ~14k; IRF ~1.2k); partitioned by (setting, year), 2014-2023, 5 settings.","summary_category mixes aggregation levels (filter to provider-level rows via prvdr_id); tot_outlier_payment_amt null for SNF/hospice (column absent there).","Curated common core (~20 cols) of the 69-82-col per-setting files; the 50+ chronic-condition % cols are skipped (full files at source)."],"notes":"Iceberg medicare_silver.fact_post_acute_utilization, partitioned by (setting, year) so each setting-year CSV is its own replace-safe partition.","tools":[]},{"source_id":"cms_aco_participant","source_fqn":"medicare_silver.fact_aco_participant","title":"CMS Accountable Care Organization (ACO) Participants — Shared Savings Program","domain":"medicare","stage":"silver","status":"live","grain":"One source row per (performance_year, ACO, participant legal business name); participant TIN is not retained, so this nominal key is not unique.","description":"The CMS Medicare Shared Savings Program ACO Participants list per ACO and participating organization: ACO id/name, service area, agreement period, track, revenue class, assignment type, and address. Production holds 2016-2026. Official 2014-2015 files are ID-less and owner-deferred; 2013 was not recovered.","identity_key":"aco_id","row_count":183710,"last_updated":null,"freshness_sla":"Annual (MSSP performance year).","recollection":{"cadence":"annual","watermark_field":"performance_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'performance_year' is the MSSP vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_aco_participant","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/cms_programs.md","known_gaps":["Participant org is by legal business name; the source participant TIN is omitted from the curated subset, so repeated ACO/LBN rows can represent distinct TINs and the nominal key is not unique.","Program year 2013 was not recovered after data.json, direct URL, and Wayback probes. Official 2014-2015 files lack ACO ID and were owner-deferred rather than forced into this keyed table."],"notes":"Iceberg medicare_silver.fact_aco_participant, partition by performance_year, replace.","tools":[]},{"source_id":"cms_mdpp_supplier","source_fqn":"medicare_silver.dim_mdpp_supplier","title":"Medicare Diabetes Prevention Program (MDPP) Suppliers","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per MDPP supplier location (by row_seq within state).","description":"The roster of Medicare Diabetes Prevention Program (MDPP) suppliers — CMMI-model organizations enrolled to furnish the DPP benefit, with organization/location name, address, NPI, and category. The DPP innovation- model participation list (~1,037 suppliers).","identity_key":"npi","row_count":1037,"last_updated":null,"freshness_sla":"Refreshed as CMS republishes the MDPP supplier list.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_mdpp_supplier","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/cms_programs.md","known_gaps":["Snapshot (current); NPI present for most but not all suppliers."],"notes":"Iceberg medicare_silver.dim_mdpp_supplier, partition by state, replace.","tools":[]},{"source_id":"cms_qpp_experience","source_fqn":"medicare_silver.fact_qpp_experience","title":"CMS Quality Payment Program (QPP/MIPS) Experience — clinician scores","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, clinician record) — MIPS final score + category scores + payment adjustment.","description":"The CMS Quality Payment Program Experience file — per clinician (provider key / NPI) the MIPS final score, payment adjustment percentage, and the four category scores (quality, promoting interoperability, improvement activities, cost), plus practice size, specialty, participation option, and small/rural/ HPSA status. The clinician value-based-performance layer. ~500k-1.05M clinicians/year, 2017-2024. Curated ~21-col subset of the 212-col file.","identity_key":"npi","row_count":503917,"last_updated":null,"freshness_sla":"Annual (QPP performance year).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the QPP performance year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_qpp_experience","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/cms_programs.md","known_gaps":["row_count is per year (2024 ~504k; 2017 ~1.05M); ALWAYS filter data_year. row_seq makes each record unique.","Curated ~21-col subset of 212 (final/category scores + payment adjustment + practice attributes; the per-measure detail columns are at the source).","npi can be blank for some records (provider_key is the always-present key)."],"notes":"Iceberg medicare_silver.fact_qpp_experience, partition by data_year, replace.","tools":[]},{"source_id":"cms_medicaid_managed_care","source_fqn":"medicare_silver.fact_medicaid_managed_care","title":"CMS Medicaid Managed Care (utilization by MCO × county)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (calendar_year, state, county, MCO, service category).","description":"CMS Medicaid Managed Care utilization — per state, county, managed-care organization, and service category: active patients, eligible MCO patients, providers, % of eligible receiving services, services per active patient. The Medicaid MCO access/utilization lens (note: Medicaid managed-care utilization, not medical rates — those remain unavailable).","identity_key":"mco_name","row_count":19559,"last_updated":null,"freshness_sla":"Annual.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the source's vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_medicaid_managed_care","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/cms_programs.md","known_gaps":["Source files carry overlapping multi-year ranges; per-year replace keeps the latest (2019-2024 net). Utilization/access only, NOT Medicaid medical rates."],"notes":"Iceberg medicare_silver.fact_medicaid_managed_care, partition by calendar_year, replace.","tools":[]},{"source_id":"cms_idr_determination","source_fqn":"medicare_silver.fact_idr_determination","title":"CMS Federal IDR (No Surprises Act) Determinations — OON arbitration fair price","domain":"commercial","stage":"silver","status":"live","grain":"One row per OON dispute line item (year, quarter, row_seq) — outcome + offers as % of QPA.","description":"The CMS Federal Independent Dispute Resolution (No Surprises Act) Public Use Files — every out-of-network payment-determination line item: who prevailed (provider vs plan), the provider/plan/prevailing **offer as a % of the QPA** (Qualifying Payment Amount), QPA as % of median, by service code (CPT/HCPCS), place of service, location (state), specialty, practice size, and plan type. A FEDERALLY-SOURCED, market-derived **fair-price benchmark** for OON commercial claims — anchors fair-RBP / overpayment arguments with arbitration reality instead of a model alone. Core \"OON Emergency and Non-Emergency\" sheet.","identity_key":"provider_npi","row_count":947216,"last_updated":null,"freshness_sla":"Quarterly (CMS No Surprises reports page) + bi-monthly interim.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' (+ quarter) is the source's documented vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_determination","commercial_terms":"Public CMS data; freely redistributable (per PUF user agreement).","provenance_chain_ref":"medicare_silver M-2 substrate (sha256 + source_url + asserted_at on every row).","context_doc_path":"docs/context_library/commercial/idr_no_surprises.md","known_gaps":["row_count is per quarter (2024Q4 ~947k 'OON Emergency and Non-Emergency' rows); ~10 quarters 2023Q1-2025Q2, partition by (year, quarter).","HEAVY: 200-385MB XLSX/ZIP per quarter; full backfill on the worker fleet (job_type build_idr_determination). Source is the www.cms.gov reports page (curl), not the data API.","Only the core OON Emergency & Non-Emergency sheet is loaded; the 'OON Air Ambulance' + 'QPA and Offers' sheets in each workbook are not yet ingested.","Offer-%-of-QPA values are percents (e.g. 1046 = 1,046% = 10.46x QPA); 'N/A' coerced to null."],"notes":"Iceberg medicare_silver.fact_idr_determination, partition by (year, quarter); bulk-load (append_buffered per 200k chunk -> flush_buffered_replace_partitions per quarter, atomic). row_seq makes each line-item row unique.","tools":[]},{"source_id":"cms_psps","source_fqn":"medicare_silver.fact_psps","title":"CMS Physician/Supplier Procedure Summary (PSPS) — granular Part B allowed","domain":"medicare","stage":"silver","status":"live","grain":"One row per (data_year, HCPCS × modifiers × specialty × carrier-locality × type-of-service × place-of-service).","description":"The CMS Physician/Supplier Procedure Summary — Part B submitted/allowed/ denied service counts + charges + NCH payment at HCPCS × modifier × provider specialty × carrier-locality × type-of-service × place-of-service. The most granular public Part B allowed-amount benchmark (finer than the by-geography PUFs). ~14.4M rows/year, 2010-2024, partition by data_year.","identity_key":"hcpcs_cd","row_count":14377293,"last_updated":null,"freshness_sla":"Annual (CMS PSPS).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_psps","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/psps_and_discarded_drug.md","known_gaps":["~14.4M rows/year (836MB CSV); ALWAYS filter data_year. HEAVY — full 2010-2024 backfill on the worker fleet (job_type build_psps_discarded); 2024 proof loaded.","allowed/payment are Part B; row_seq keys each row (the natural grain is the full code×modifier×spec×locality×tos×pos tuple)."],"notes":"Iceberg medicare_silver.fact_psps, partition by data_year; bulk-load (append_buffered 300k -> flush per year).","tools":[]},{"source_id":"cms_drug_discarded_units","source_fqn":"drug_silver.fact_drug_discarded_units","title":"CMS Medicare Part B Discarded Drug Units (JW/JZ waste)","domain":"drug","stage":"silver","status":"live","grain":"One row per (data_year, HCPCS) — administered vs discarded allowed amount + % units.","description":"CMS Medicare Part B Discarded Drug Units — per drug HCPCS the total Medicare allowed amount split into administered vs discarded, plus % administered/ discarded units. The drug-WASTE / IRA single-dose-vial refund overpayment vector — join to ASP to value waste and surface JW-refund recovery.","identity_key":"hcpcs_cd","row_count":824,"last_updated":null,"freshness_sla":"Annual (CMS).","recollection":{"cadence":"annual","watermark_field":"data_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'data_year' is the source's documented vintage column."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_discarded_units","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/psps_and_discarded_drug.md","known_gaps":["Current snapshot (2023); join hcpcs_cd to drug_asp to value the discarded $ for JW-refund overpayment."],"notes":"Iceberg drug_silver.fact_drug_discarded_units, partition by data_year, replace.","tools":[]},{"source_id":"cms_tc_puf_issuer_claims","source_fqn":"medicare_silver.fact_tc_puf_issuer_claims","title":"CMS CCIIO Transparency in Coverage PUF — issuer claims denial / appeal behavior","domain":"commercial","stage":"silver","status":"live","grain":"One row per (plan_year, Marketplace plan_id) — issuer claims received/denied/appealed + denial reasons.","description":"The CMS CCIIO Transparency in Coverage PUF (data.healthcare.gov) — per ACA Marketplace issuer/plan: claims received / DENIED / resubmitted (out-of-network + in-network), internal & external appeals filed/overturned, plan-level denial REASONS (referral required, OON, services excluded, not medically necessary, benefit-limit, investigational, administrative, other), plus rate-review + NAIC-financial links and avg monthly enrollment/disenrollment. The PAYER- BEHAVIOR / denial-rate signal — rank issuers by denial/overturn, benchmark a client's denial experience. ~5-7k plans/year, PY2022-2026.","identity_key":"issuer_id","row_count":6764,"last_updated":null,"freshness_sla":"Annual (plan year).","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' is the source's documented vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_tc_puf_issuer_claims","commercial_terms":"Public CMS/CCIIO data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/commercial/tc_puf_issuer_claims.md","known_gaps":["Individual-market medical QHP sheet only (Ind QHP); the Ind SADP (dental) + SHOP sheets in each workbook are not yet ingested.","PY2017 is a CSV variant (different layout) not yet handled; PY2018-2021 are not published by CMS. Loaded years = PY2022-2026.","Suppressed cells (** / * / N/A) coerced to null; plan-level denial-reason columns are sparsely populated."],"notes":"Iceberg medicare_silver.fact_tc_puf_issuer_claims, partition by plan_year, replace. XLSX 'Transparency YYYY - Ind QHP' sheet, dynamic header detection (2 title/legend rows).","tools":[]},{"source_id":"cms_hpsa","source_fqn":"medicare_silver.fact_hpsa","title":"HRSA Health Professional Shortage Areas (HPSA) — PC / Dental / Mental Health","domain":"provider_identity","stage":"silver","status":"live","grain":"One row per (observed_period, discipline, row_seq) — Wayback-vintage snapshots 2020-2026 plus the current HRSA extract","description":"The mastered HRSA HPSA cumulative daily extract across primary care, dental, and mental health: 1,040,138 rows across 22 (observed_period, discipline) vintage slices.","identity_key":"observed_period,discipline,row_seq","row_count":1040138,"last_updated":"2026-07-11","freshness_sla":"Refreshed as HRSA updates designations (frequent).","recollection":{"cadence":"continuous","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Wayback capture downloads may require pacing of 45s+ with retry because web.archive.org connection-refuses fleet IPs on rapid sequential downloads.","SSM background launches require setsid + flock singleton; resume-safe re-execution absorbed one EC2 health-check replacement."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hpsa","commercial_terms":"Public HRSA data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/hpsa.md","known_gaps":["2009-2015 exists only as datawarehouse.hrsa.gov HPSA.zip Wayback captures; ZIP contents/schema are unknown and the parser has no ZIP support. Do not load without a reviewed legacy parser plus schema mapping.","2016-2017 BCD_HPSA_FCT_DET_*.csv captures download but fail the fail-closed parser because the HPSA ID header is missing. Do not load without a reviewed header-mapping era adapter.","Serving pin: current consumers must filter observed_period = max(observed_period) per discipline; there is no direct repo consumer and no serving view.","is_current means current-at-capture; row_seq keys are not stable across vintages and is_current is not a cross-vintage serving selector.","Wayback provenance grade: historical captures are web-archive captures of the publisher file (raw-bytes id_ URLs), not publisher-hosted archives; unchanged bytes are skipped as DUPLICATE_CONTENT_SKIP."],"notes":"Iceberg medicare_silver.fact_hpsa, partition and replace scoped by (observed_period, discipline); identifiers are (observed_period, discipline, row_seq); one SHA per slice; registry skips distinguish IDEMPOTENT_SKIP from DUPLICATE_CONTENT_SKIP.","tools":[]},{"source_id":"fda_gudid_device","source_fqn":"drug_silver.dim_device_udi","title":"NLM AccessGUDID — Device Identity (FDA Global UDI Database)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per device (release_month, PrimaryDI) — brand/model/company + flags.","description":"The FDA Global UDI Database (via NLM AccessGUDID) — every marketed medical device by its Device Identifier (PrimaryDI): brand, version/model, catalog number, company (DUNS), description, commercial-distribution status, and flags (single-use, sterile, MRI safety, Rx/OTC, kit, combination product). Resolves the UDI/DI on an itemized bill or implant log to canonical device identity — de-anonymizes high-cost implant/device line items driving chargemaster markups. ~5.1M devices, partition by release_month.","identity_key":"primary_di","row_count":5129241,"last_updated":"2026-07-12","freshness_sla":"Monthly (AccessGUDID full release).","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (monthly release)."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_device_udi","commercial_terms":"Public FDA/NLM data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/gudid_device.md","known_gaps":["Historical 2015-2025 GUDID replay is an external source limit: NLM historical full-release objects require a publisher-side Glacier restore and are not retrievable by client-side action; 2015-2018 standard URLs are additionally unresolved/404.","Reopen only if NLM restores or fulfills a restore request and provides a restored/staged ZIP manifest with GET-proven bytes, full SHA, and dry-run row/skips proof; current 2026-06 snapshot semantics remain unchanged."],"notes":"Iceberg drug_silver.dim_device_udi, partition by release_month; bulk-load (append_buffered 300k -> flush).","tools":[]},{"source_id":"cms_rate_puf","source_fqn":"medicare_silver.fact_rate_puf","title":"CMS CCIIO Rate PUF — ACA Marketplace QHP plan premium rates","domain":"commercial","stage":"silver","status":"live","grain":"One row per (business_year, issuer × plan × rating-area × age × tobacco) — individual + family premiums.","description":"The CMS CCIIO Rate PUF (data.healthcare.gov) — the actual filed monthly premium for every ACA Marketplace QHP by issuer × plan × rating area × age × tobacco status: individual rate, individual-tobacco rate, and family-tier rates (couple, +1/+2/+3 dependents). A commercial PRICE signal (plan premium geography by issuer/area/age) independent of TiC negotiated rates + hospital chargemaster — the premium side of the commercial market. ~2-3M rows/year, PY2014-2026, partition by business_year.","identity_key":"issuer_id","row_count":2235761,"last_updated":null,"freshness_sla":"Annual (plan year).","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'business_year' is the source's documented plan-year column."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_rate_puf","commercial_terms":"Public CMS/CCIIO data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/commercial/rate_puf.md","known_gaps":["Premium rates (the price of coverage), NOT provider payment rates — complements TiC (what the plan pays providers) with what the member pays for the plan.","~2-3M rows/year; ALWAYS filter business_year. Age is a string bucket ('0-14','21','64 and over'); rating_area_id is the CCIIO geographic rating area.","13 years PY2014-2026; bulk-load (append_buffered 300k -> flush per year)."],"notes":"Iceberg medicare_silver.fact_rate_puf, partition by business_year; bulk-load. row_seq keys each row.","tools":[]},{"source_id":"cms_hcahps_hospital","source_fqn":"medicare_silver.fact_hcahps","title":"CMS Care Compare HCAHPS — Hospital patient-experience survey","domain":"medicare","stage":"silver","status":"live","grain":"One row per (reporting_year, CCN × HCAHPS measure) — long-format measure row; writer key (reporting_year,row_seq).","description":"The HCAHPS hospital patient-experience survey (CMS Care Compare): one long-format row per hospital CCN and HCAHPS measure for each reporting_year, carrying patient-survey star rating, answer percent, linear-mean value, completed surveys, and response rate.","identity_key":"ccn","row_count":4208689,"last_updated":"2026-07-11","freshness_sla":"CMS Care Compare refresh; use reporting_year as the vintage selector.","recollection":{"cadence":"annual","watermark_field":"reporting_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field reporting_year is derived from the survey end_date.","Live readback Athena query 4efc78f6-e858-4eae-8706-2813c6f0344b proves reporting_year 2014-2025, 4,208,689 rows, one SHA per year, and zero source_url nulls."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hcahps","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/hcahps.md","known_gaps":["hcahps_mdb_era_gate: 2008-2011 official Hospital Compare archives contain HCAHPS only inside monolithic MS Access Hospital.mdb; reviewed MDB extraction (mdbtools) plus schema mapping is required.","hcahps_wide_format_era_gate: 2012-2013 official Hospital Compare CSVs are wide-format with one row per hospital, per-question percent columns, and Provider Number; reviewed wide-to-long melt plus question-text-to-measure-ID crosswalk is required, and the fail-closed parser rejects them today.","Live coverage is reporting_year 2014-2025 with 4,208,689 rows; 2014 has a smaller measure set and row count as source reality, not a defect.","No direct repo consumers. Hold vintage and measure constant; cross-era comparisons must hold measure ID + answer description constant because no cross-era crosswalk exists.","Official archive URLs are case-sensitive: the 2015 path uses FlatFiles capitalization."],"notes":"Iceberg medicare_silver.fact_hcahps, partition by reporting_year with replace semantics. Join ccn to dim_facility / fact_hospital_quality_measure.","tools":[]},{"source_id":"cms_hospice_quality","source_fqn":"medicare_silver.fact_hospice_quality","title":"CMS Care Compare Hospice provider-quality measures","domain":"medicare","stage":"silver","status":"live","grain":"One row per (reporting_year, hospice CCN × measure code) — quality score.","description":"CMS Care Compare hospice provider-quality (long format): per hospice (CCN) × quality measure code/name → score (+ footnote). The post-acute (hospice) quality comparability dimension, alongside hospital quality / HCAHPS / SNF. ~459k rows, partition by reporting_year.","identity_key":"ccn","row_count":459084,"last_updated":null,"freshness_sla":"Quarterly refresh (CMS Care Compare).","recollection":{"cadence":"derived","watermark_field":"reporting_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'reporting_year' = the M-2 load year (snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospice_quality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/hospice_quality.md","known_gaps":["Snapshot (reporting_year = load year; source carries no period column); suppressed scores -> null.","Provider-level Hospice CAHPS survey is a separate dataset (not this provider-quality file)."],"notes":"Iceberg medicare_silver.fact_hospice_quality, partition by reporting_year, replace. Join ccn to dim_hospice.","tools":[]},{"source_id":"state_medicaid_fee_schedule","source_fqn":"vlada_curated.fact_state_medicaid_rate","title":"State Medicaid Fee Schedule (rate per CPT/HCPCS)","domain":"state","stage":"silver","status":"live","grain":"One row per (state, procedure/HCPCS) — Medicaid allowed rate.","description":"Per-state Medicaid rate per code (the Medicaid floor). MD professional ingested (9,152). Tool ingest_state_medicaid.py; M-2 temporal.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"md_hscrc_unit_rate","source_fqn":"vlada_curated.fact_md_hscrc_unit_rate","title":"MD HSCRC All-Payer Hospital Unit Rates","domain":"state","stage":"silver","status":"live","grain":"One row per (rate_year, hospid, cost_center, effective_date, line_seq)","description":"MD all-payer approved unit rate per HSCRC hospital id and cost center across RY2013-RY2024 and RY2026 (22,588 rows). Effective-date changes and source-real split rate lines are preserved. Federal CCN/NPI joins require a bridge. Tool ingest_hscrc_rates.py.","identity_key":null,"row_count":22588,"last_updated":"2026-07-11","freshness_sla":"Annual rate-year refresh.","recollection":{"cadence":"annual","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":["Split rate lines are source reality: special-status hospitals can carry multiple simultaneous rows for one (cost_center, effective_date) with different rates and volumes; line_seq preserves every line and consumers must aggregate or select by volume context.","RY2021 has 34 unparseable effective-date rows quarantined and counted; raw_effective_text is preserved and those rows are never loaded.","RY2025 remains blocked by the recorded Northwest Hospital Center / hospid 40 / 1900-02-09 defect; its partition was previously removed.","Legacy vintages predate line_seq and retain NULL line_seq; their original four-part proofs stand."],"notes":null,"tools":[]},{"source_id":"ma_chia_relative_price","source_fqn":"vlada_curated.fact_ma_chia_relative_price","title":"MA CHIA Relative Price (commercial price variation)","domain":"state","stage":"silver","status":"live","grain":"One row per (payer, hospital) — MA commercial relative price (1.0=statewide median).","description":"MA commercial price variation per payer x hospital (CY2023, 4,357; 1.0=statewide median). Tool ingest_chia_relative_price.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":["Byte-secured deferred lane: five workbooks / zero misses under s3://vlada-platform-raw/medicare/bronze/ma_chia_rp_archive/; CY2019 is enumerated-not-secured and CY2020 is already held.","Writer safety is unresolved: the current tool appends hash-named Parquet under data_year without partition replacement, supersession, or idempotency checks; re-derive the canonical grain before replay."],"notes":"MA CHIA relative-price archive is byte-secured but deferred behind the modern versioned writer/key contract and legacy CY2011-CY2017 era adapters.","tools":[]},{"source_id":"cms_home_health_quality","source_fqn":"medicare_silver.fact_home_health_quality","title":"CMS Care Compare Home Health Agencies — per-agency quality","domain":"medicare","stage":"silver","status":"live","grain":"One row per (reporting_year, home-health agency CCN) — star rating, measure rates, DTC/PPR/PPH, spending.","description":"CMS Care Compare Home Health Agencies (wide per-agency): identity + ownership + service-offering flags + patient-care star rating + key quality-measure rates + DTC/PPR/PPH risk-standardized rates + Medicare spending ratio. The home-health quality comparability dimension. ~12.4k agencies, curated ~30 of 96 columns.","identity_key":"ccn","row_count":12392,"last_updated":null,"freshness_sla":"Quarterly refresh (CMS Care Compare).","recollection":{"cadence":"derived","watermark_field":"reporting_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'reporting_year' = the M-2 load year (snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_home_health_quality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/home_health_quality.md","known_gaps":["Snapshot (reporting_year = load year); suppressed values -> null. HHCAHPS patient survey is a separate dataset.","Curated ~30 of 96 cols (drift known-list = mapped+all-header)."],"notes":"Iceberg medicare_silver.fact_home_health_quality, partition by reporting_year, replace. Join ccn to dim_hha.","tools":[]},{"source_id":"cms_nursing_home_quality","source_fqn":"medicare_silver.fact_nursing_home_quality","title":"CMS Care Compare Nursing Home (Provider Information) — 5-star quality","domain":"medicare","stage":"silver","status":"live","grain":"One row per (reporting_year, nursing-home CCN) — 5-star ratings, beds, staffing, deficiencies.","description":"CMS Care Compare Nursing Home Provider Information (wide per-facility): the 5-star ratings (overall / health-inspection / QM / long+short-stay / staffing), certified beds, ownership + chain, staffing hours-per-resident-per-day + turnover, deficiency/fine/penalty counts + geo. The nursing-home quality comparability dimension. ~14.7k facilities, curated ~45 of 99 columns.","identity_key":"ccn","row_count":14695,"last_updated":null,"freshness_sla":"Monthly refresh (CMS Care Compare).","recollection":{"cadence":"derived","watermark_field":"reporting_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'reporting_year' = the M-2 load year (snapshot)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_nursing_home_quality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/nursing_home_quality.md","known_gaps":["Snapshot (reporting_year = load year); suppressed values -> null. MDS/claims quality-measure detail is a separate dataset.","Curated ~45 of 99 cols (drift known-list = mapped+all-header)."],"notes":"Iceberg medicare_silver.fact_nursing_home_quality, partition by reporting_year, replace. Join ccn to dim_snf.","tools":[]},{"source_id":"fda_faers_drug","source_fqn":"drug_silver.fact_faers_drug","title":"FDA FAERS — Adverse-Event Drug Involvement (DRUG file)","domain":"drug","stage":"silver","status":"live","grain":"Load-ready physical row grain is (report_quarter, row_seq); noncumulative-quarter and case-version analytical semantics remain pending acceptance.","description":"FDA FAERS (Adverse Event Reporting System) DRUG file — per adverse-event report × drug: the drug's role (PS primary-suspect / SS secondary / C concomitant / I interacting), drug name, active ingredient, NDA number, route/dose, dechallenge/ rechallenge. The drug-safety surveillance signal — links adverse events to the drug substrate (join drugname/prod_ai/nda_num to dim_drug / dim_drug_application). ~2-4M rows/quarter; 2025Q1 loaded.","identity_key":"report_quarter,row_seq (physical key pending acceptance of this key or a proven alternative)","row_count":2008163,"last_updated":"2026-07-11","freshness_sla":"Quarterly (FDA FAERS ASCII release).","recollection":{"cadence":"quarterly","watermark_field":"report_quarter","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'report_quarter' is the FAERS release quarter."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_faers_drug","commercial_terms":"Public FDA data; freely redistributable.","provenance_chain_ref":"drug_silver M-2 substrate.","context_doc_path":"docs/context_library/drug/faers_drug.md","known_gaps":["Evidence-complete dry-run state: all 48 quarters 2013Q1-2024Q4 passed with zero failures and zero skipped rows against deterministic https://fis.fda.gov/content/Exports/faers_ascii_YYYYqQ.zip URLs; per-quarter rows/skips/bytes/full-SHA/source-URL evidence is at s3://vlada-platform-raw/drug/bronze/faers_archive/dryrun_evidence_2026-07-11.txt. The current loaded/proven era remains 2025Q1, and 2004Q1-2012Q4 remain source-limit at fis.fda.gov unless a separate LAERS archive is accepted.","Exact load gate: certify the physical key ((report_quarter, row_seq) or a proven alternative) and define noncumulative-quarter and case-version analytical semantics; FAERS case reports get revised across quarters, so primaryid/caseid versioning must be a documented consumer rule before production replay.","Dedicated Fargate dry-run task image lacks curl; this is an external infrastructure defect. The medicare fleet-box lane is the working evidence path."],"notes":"Iceberg drug_silver.fact_faers_drug, partition by report_quarter; bulk-load (append_buffered 300k -> flush); no historical production replay until the exact physical-key and case-version gate is accepted.","tools":[]},{"source_id":"ct_medicaid_provider_rate","source_fqn":"vlada_curated.fact_ct_medicaid_provider_rate","title":"CT Medicaid Inpatient Hospital Base Rates","domain":"state","stage":"silver","status":"live","grain":"One row per (CT Medicaid provider/procedure) — Medicaid allowed rate.","description":"CT Medicaid (CMAP) inpatient per-hospital base rate keyed to CCN, EULA-free DRG Calculator. 48 hospitals. Tool ingest_ct_medicaid_inpatient.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"ct_medicaid_drg_weight","source_fqn":"vlada_curated.fact_ct_medicaid_drg_weight","title":"CT Medicaid DRG Weights","domain":"state","stage":"silver","status":"live","grain":"One row per (DRG) — CT Medicaid inpatient DRG relative weight.","description":"CT Medicaid DRG weights/ALOS/outlier (1,342). payment=base_rate x weight. Tool ingest_ct_medicaid_inpatient.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"cms_ambulance_fee_schedule","source_fqn":"medicare_silver.fact_ambulance_fee_schedule","title":"CMS Medicare Ambulance Fee Schedule (AFS) Public Use File","domain":"medicare","stage":"silver","status":"live","grain":"One row per (year, effective_period_start, effective_period_end, HCPCS × carrier × locality) — ambulance fee-schedule rates.","description":"The standalone CMS Medicare Ambulance Fee Schedule (AFS PUF) — per HCPCS (A0425-A0436 + mileage) × carrier × locality: RVU, GPCI, base rate, and urban/rural base + mileage rates. NOT inside PFS/OPPS/CLFS/DMEPOS/ASC; the reference benchmark for repricing ambulance claims (a top balance-billing / overpayment category). ~1.3k rows/year, CY2004-CY2026, partition by year; CY2004 is represented by two effective-period half-year vintages.","identity_key":"hcpcs","row_count":29160,"last_updated":null,"freshness_sla":"Annual (CMS AFS PUF).","recollection":{"cadence":"annual","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is the AFS calendar year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ambulance_fee_schedule","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate.","context_doc_path":"docs/context_library/medicare/ambulance_fee_schedule.md","known_gaps":["carrier/locality keyed (join to medicare_county_to_locality for geography); $/n/a coerced to float/null.","CY2004 has Jan-Jun and Jul-Dec half-year vintages; downstream joins/comparisons must include effective_period_start/effective_period_end, not just year/HCPCS/carrier/locality.","Years 2004-2026 loaded and idempotency-proven; CY2003 and earlier belong to the separate reasonable-charge methodology, not this AFS PUF source."],"notes":"Iceberg medicare_silver.fact_ambulance_fee_schedule, partition by year, replace. Source = cms.gov AFS PUF annual/semiannual zip. Current proof: 29,160 rows, CY2004-CY2026, 24 source hashes, zero lineage-null rows, zero duplicate effective-period keys.","tools":[]},{"source_id":"md_hscrc_monthly_rev_vol","source_fqn":"vlada_curated.fact_md_hscrc_monthly_rev_vol","title":"MD HSCRC Monthly Revenue & Volumes","domain":"state","stage":"silver","status":"live","grain":"One row per (hospital, month) — MD HSCRC monthly revenue/volume.","description":"MD hospital revenue+volume per hospital x month x rate-center (the operationalized GBR). 15,432 rows, 61 hospitals. Tool ingest_hscrc_monthly.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"ma_chia_revenue_cost_ratio","source_fqn":"vlada_curated.fact_ma_chia_revenue_cost_ratio","title":"MA CHIA Revenue-to-Cost Ratio by Payer","domain":"state","stage":"silver","status":"live","grain":"One row per (hospital, year) — MA CHIA revenue-to-cost ratio.","description":"MA per-hospital revenue-to-cost ratio by payer (commercial 1.25x vs Medicaid 0.82x cost). 61 hospitals. Tool ingest_chia_profiles.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"cms_hospice_pps_rate","source_fqn":"medicare_silver.fact_hospice_pps_rate","title":"CMS Hospice PPS Per-Diem Rates (Federal Register final rule)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (fiscal_year, quality_compliant, level_of_care) — hospice per-diem rate.","description":"CMS Hospice PPS per-diem payment rates, extracted from CMS transmittals and Federal Register final-rule tables: Routine Home Care, Continuous Home Care (+ hourly), Inpatient Respite Care, General Inpatient Care — full rates + reduced rates for hospices not meeting quality reporting. The hospice repricing benchmark for the 9k+ hospices we roster (dim_hospice); wage index applies by CBSA on top. Each load is VALIDATED against the rule's stated rate. FY2005-FY2026 are live and proven: FY2005-FY2013 standard pre-HQRP CMS transmittal years, FY2014-FY2015 legacy single-RHC years, FY2016's exact Oct-Dec single-RHC plus Jan-Sep two-tier transition, and FY2017-FY2026 modern two-tier-RHC years.","identity_key":"level_of_care","row_count":164,"last_updated":null,"freshness_sla":"Annual (hospice wage index & payment rate final rule).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the hospice PPS fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospice_pps_rate","commercial_terms":"Public CMS / Federal Register data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS transmittals and Federal Register final rule.","context_doc_path":"docs/context_library/medicare/hospice_pps_rate.md","known_gaps":["Standardized federal per-diems; multiply the labor portion by the hospice CBSA wage index for a facility-specific rate.","FY2016 contains three distinct RHC levels at non-overlapping effective periods; always filter by service date and level_of_care for historical repricing.","FY2005-FY2013 rows are standard pre-HQRP CMS transmittal rows only; no reduced-quality rows are invented, and base_rate is null by source-era design.","Program inception and pre-FY2005 rate-file availability remain unproven; FY2005 is the earliest recovered official transmittal in this campaign.","The table carries standardized per-diems and the CHC hourly SIA basis, not patient-specific SIA eligibility/hours or separate labor/nonlabor components."],"notes":"Iceberg medicare_silver.fact_hospice_pps_rate, partition by fiscal_year, replace. Sourced via pipelines/medicare/ingest/hospice_pps_runner.py using CMS transmittal PDFs, structured FR XML, explicitly accepted PDF text, or SHA-locked verified image-table maps. Parser 1.0.3 adds the SHA-locked FY2016 transition adapter plus a pre-write natural-key/effective-period guard.","tools":[]},{"source_id":"ct_hospital_cost_to_charge","source_fqn":"vlada_curated.fact_ct_hospital_cost_to_charge","title":"CT OHS Hospital Cost-to-Charge Ratios","domain":"state","stage":"silver","status":"live","grain":"One row per (hospital, year) — CT hospital cost-to-charge ratio.","description":"CT per-hospital cost-to-charge ratio (RCC, FY2024), 27 hospitals/6 systems. JS-rendered /-/media/ link found via headless browse. Tool ingest_ct_ohs_ccr.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'asserted_at' is the M-2 publication-date stamp (state-data fleet)."]},"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]},{"source_id":"cms_irf_pps_cmg_weight","source_fqn":"medicare_silver.fact_irf_pps_cmg_weight","title":"CMS IRF PPS CMG Relative Weights (rule data files)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (fiscal_year, effective_period_start, effective_period_end, CMG, comorbidity tier) — relative weight + ALOS + standard payment amount.","description":"CMS Inpatient Rehabilitation Facility PPS case-mix table — per Case-Mix Group (CMG) x comorbidity tier (1/2/3/none): the relative weight, average length of stay, and the official IRF standard payment conversion factor. Sourced from annual IRF PPS rule data files and FY2006 CMS-1290-F Table 4, anchor-VALIDATED against published weights. Reprices IRF claims for the 666 IRFs we roster (dim_irf): payment ~= std_payment_amount x relative_weight x wage index x adjustments. Source-truth coverage is FY2006-FY2026 after the 2026-07-05 effective-period replay, FY2014 recovery, and FY2006 Table 4 recovery.","identity_key":"cmg","row_count":8443,"last_updated":null,"freshness_sla":"Annual (IRF PPS final rule).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the IRF PPS fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_irf_pps_cmg_weight","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS rule data files plus CMS-1290-F Table 4 / CMS-1290-CN for FY2006.","context_doc_path":"docs/context_library/medicare/irf_pps_cmg_weight.md","known_gaps":["std_payment_amount is the official IRF standard payment conversion factor ($19,371 FY2026 after correction), not the intermediate pre-neutrality standard amount.","FY2006 uses CMS-1290-F final-rule PDF Table 4 for CMG weights/ALOS and CMS-1290-CN for the corrected $12,762 standard payment conversion factor.","FY2008 and FY2010 have mid-year standard-payment-factor changes and are represented with effective_period_start/effective_period_end rows; joins must include effective period, not fiscal_year alone."],"notes":"Iceberg medicare_silver.fact_irf_pps_cmg_weight, partition by fiscal_year, replace. Source = CMS rule data-files zip (nested CMG_ALOS CSV) plus FY2006 CMS-1290-F Table 4 PDF extraction. Current proof: 8,443 rows, 21 fiscal-year vintages, 20 source hashes, zero duplicate effective-period keys, zero lineage-null rows.","tools":[]},{"source_id":"cms_hh_pdgm_weight","source_fqn":"medicare_silver.fact_hh_pdgm_weight","title":"CMS Home Health PDGM Case-Mix Weights","domain":"medicare","stage":"silver","status":"live","grain":"One row per (calendar_year, HIPPS) — recalibrated PDGM case-mix weight + LUPA threshold.","description":"CMS Home Health Patient-Driven Groupings Model (PDGM) case-mix table — per HIPPS code (432): clinical group + admission source/timing + comorbidity adjustment, the recalibrated case-mix WEIGHT, and the LUPA visit threshold. Sourced from the CMS Home Health PPS Case-Mix Weights zip (clean XLSX) and anchor-VALIDATED (HIPPS 1FC11 = 1.0804). Reprices HH 30-day periods for the 23k+ HHAs we roster (dim_hha): payment ~= 30-day base rate x recalibrated_weight x wage index. CY2026 live. Third full non-acute repricer.","identity_key":"hipps","row_count":432,"last_updated":null,"freshness_sla":"Annual (HH PPS final rule; case-mix recalibrated periodically).","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the HH PPS calendar year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hh_pdgm_weight","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS HH PPS case-mix weights file.","context_doc_path":"docs/context_library/medicare/hh_pdgm_weight.md","known_gaps":["Case-mix WEIGHTS + LUPA thresholds (validated). The CY 30-day national standardized base payment rate (a single scalar) is NOT included here — pin it from the rule (CY2024 ref ~$2,038) and multiply; deliberately not guessed (wrong base = wrong reprice).","CY2026 loaded; add prior years (2014-2025 zips published) by mapping calendar_year -> zip + anchor."],"notes":"Iceberg medicare_silver.fact_hh_pdgm_weight, partition by calendar_year, replace. Source = CMS HH PPS Case-Mix Weights annual zip.","tools":[]},{"source_id":"cms_fqhc_pps_rate","source_fqn":"medicare_silver.fact_fqhc_pps_rate","title":"CMS FQHC PPS Base Payment Rate","domain":"medicare","stage":"silver","status":"live","grain":"One row per calendar_year — the national FQHC PPS per-visit base payment rate.","description":"CMS Federally Qualified Health Center PPS national per-visit base payment rate, extracted from the annual CMS Pricer-update transmittal and anchor-VALIDATED (CY2026 = $207.72). The FQHC repricing base for the FQHCs we roster — adjusted per FQHC by the Geographic Adjustment Factor (derived from the PFS GPCIs we already hold in medicare_gpci_locality) + the new-patient/IPPE/AWV adjustment. CY2025 ($202.65) + CY2026 ($207.72) live. Fifth non-acute repricer; completes the cleanly-sourceable non-acute rate set.","identity_key":"calendar_year","row_count":2,"last_updated":null,"freshness_sla":"Annual (CMS FQHC PPS Pricer update transmittal).","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the FQHC PPS calendar year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_fqhc_pps_rate","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS Pricer transmittal.","context_doc_path":"docs/context_library/medicare/fqhc_pps_rate.md","known_gaps":["Base rate only; multiply by the FQHC GAF (derive from medicare_gpci_locality) + 1.3416 new-patient/IPPE/AWV adjustment for the facility-specific per-visit payment.","CY2025-2026 from the CY2026 transmittal; add prior years via their transmittals."],"notes":"Iceberg medicare_silver.fact_fqhc_pps_rate, partition by calendar_year, replace. Source = CMS Pricer-update transmittal PDF (validated extraction).","tools":[]},{"source_id":"cms_snf_pdpm_rate","source_fqn":"medicare_silver.fact_snf_pdpm_rate","title":"CMS SNF PPS PDPM Case-Mix-Adjusted Rates (urban & rural)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (fiscal_year, urban_rural, PDPM grid row) — PT/OT/SLP/Nursing/NTA CMIs + component rates.","description":"CMS Skilled Nursing Facility PPS PDPM case-mix-adjusted federal rates by fiscal year and urban/rural setting. The complete PDPM program era FY2020-FY2026 is live: FY2020-FY2022 are SHA-locked Federal Register final-rule tables and FY2023-FY2026 are CMS 508 CSV ZIPs. Each year has the 25-row A-Y wide grid for PT, OT, SLP, Nursing, and NTA CMIs and adjusted component rates.","identity_key":"pdpm_group","row_count":350,"last_updated":null,"freshness_sla":"Annual (SNF PPS final rule).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the SNF PPS fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_snf_pdpm_rate","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS-1718-F through CMS-1827-F final-rule rate tables.","context_doc_path":"docs/context_library/medicare/snf_pdpm_rate.md","known_gaps":["Table 6 is a parallel-component grid (PT/OT 16 groups, SLP 12, Nursing 25, NTA 6) captured wide per row_seq; component rates are case-mix-adjusted (= base x CMI). Apply the variable-per-diem (VPD) day adjustment + SNF CBSA wage index for the facility-/day-specific per-diem.","The separate non-case-mix component is not in this table. Exact payment also requires HIPPS component selection, variable-per-diem policy, and the SNF wage index.","FY2020's official Table 7 caption says RUG-IV even though the table columns, values, and surrounding final-rule text identify the PDPM rural grid.","Historical rows are all valid source vintages; current serving must select the latest `fiscal_year` instead of averaging across years."],"notes":"Iceberg medicare_silver.fact_snf_pdpm_rate, partition by fiscal_year, replace. FY2020-FY2022 source = SHA-locked GovInfo Federal Register PDFs; FY2023-FY2026 source = CMS urban/rural 508 CSV ZIPs.","tools":[]},{"source_id":"cms_ltch_pps_drg_weight","source_fqn":"medicare_silver.fact_ltch_pps_drg_weight","title":"CMS LTCH PPS MS-LTC-DRG Relative Weights (Table 11)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (fiscal_year, MS-LTC-DRG) — relative weight + geometric LOS + short-stay-outlier threshold.","description":"CMS Long-Term Care Hospital PPS MS-LTC-DRG case-mix table (Table 11) — per MS-LTC-DRG: the relative weight, geometric average length of stay, and the short-stay-outlier threshold. The LTCH repricing case-mix table for the 655 LTCHs we roster (dim_ltch): payment = relative_weight x LTCH standard federal rate x wage index. Sourced from the CMS-1833-F MS-LTC-DRG File zip (clean XLSX) and anchor-VALIDATED (DRG 003 = 3.644). FY2026 live (772 DRGs). Seventh non-acute repricer — COMPLETES the non-acute PPS rate family (SNF/HH/IRF/LTCH/hospice/ ESRD-base/FQHC + ambulance).","identity_key":"ms_ltc_drg","row_count":772,"last_updated":null,"freshness_sla":"Annual (LTCH PPS / IPPS final rule).","recollection":{"cadence":"annual","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'fiscal_year' is the LTCH PPS fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ltch_pps_drg_weight","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"medicare_silver M-2 substrate; CMS-1833-F MS-LTC-DRG File (Table 11).","context_doc_path":"docs/context_library/medicare/ltch_pps_drg_weight.md","known_gaps":["Relative weights (validated). Multiply by the LTCH standard federal rate (a scalar; pin from the rule) + LTCH wage index for the payment; short-stay-outlier + site-neutral adjustments apply.","FY2026 (CMS-1833-F) loaded; prior-year Table 11 zips published (FY2021+) — map fiscal_year -> zip + anchor."],"notes":"Iceberg medicare_silver.fact_ltch_pps_drg_weight, partition by fiscal_year, replace. Source = CMS MS-LTC-DRG File (Table 11) zip.","tools":[]},{"source_id":"nj_hospital_financials","source_fqn":"vlada_curated.fact_nj_hospital_financials","title":"NJ DOH Hospital Financial Transparency","domain":"state","stage":"silver","status":"live","grain":"One row per (hospital, fiscal year) — NJ DOH operating income / revenue / margin (CY2021-23, 73 hospitals).","description":"NJ per-hospital operating income/revenue/margin (CY2021-23, 73 hospitals). Found by the verification fleet. NJ's state financial leg (no rate-setting/APCD). Tool ingest_nj_financials.py.","identity_key":null,"row_count":null,"last_updated":null,"freshness_sla":null,"recollection":null,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"tools":[]}],"tools":[{"name":"benchmark_code","version":"1.0.0","description":"Benchmark ONE payer's negotiated-rate distribution for a billing code in a state (median, p10/p25/p75/p90, min/max, mean) with provider-scope and quality breakdowns, at query time over the canonical graph + inverted indexes (no precomputed edge table). Codes: CPT/HCPCS (professional/outpatient), AND MS-DRG for INPATIENT — pass the 3-digit DRG (e.g. '470' major joint replacement) and it resolves the inpatient rates. Ghost/near-zero rates are excluded; network-level rates flagged; thin samples (<8 rates) are returned but flagged low_sample_size with reduced confidence. This is the SINGLE-PAYER view — compose cross-payer comparisons by calling once per payer. Covers all built payers (30+).","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["benchmark_mode=rate_value (not provider/utilization weighted)","medical_mutual not yet indexed"]},{"name":"care_site_price","version":"1.0.0","description":"Resolve ANY care site by NPI and return its price, read from the source-of-truth table it already lives in (a BRIDGE, never a copy). Routing: a hospital with a CCN returns its HPT from the hospital chargemaster (CCN-keyed); a provider-based outpatient site inherits its PARENT hospital's HPT; a freestanding/non-hospital site returns site-posted cash/GFE/services it published itself; an NPI-only hospital (no CCN) is routed into the hospital DB + funnel and reports pricing_pending; a federal facility (VA/DoD/IHS) reports no public price. NEGOTIATED commercial rates are NOT returned here — they are RESOLVED on demand through the engine when a `payer` is given: the NPI is resolved to that payer's provider groups + rates over its S3 index, returning the negotiated rate(s) and the CONTRACT SHAPE (fee schedule vs percentage/percent-of-charges vs not_in_network vs in_network_no_rate_in_scope). A newly-built payer is picked up with no rebuild. Without `payer`, the negotiated layer is a pointer to lookup_rates_for_npi. No rate is ever copied. Inputs: npi (required 10-digit), billing_code (optional CPT/HCPCS/DRG filter), payer (optional, e.g. 'cigna' — resolves real negotiated rates). This is the unifying serving entry for the County Intelligence / care-site substrate: identity (dim_care_site) joined to the right price source. SOURCE: NPPES/CMS registry + CMS Hospital Price Transparency MRFs + site-posted prices.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.dim_care_site","vlada_curated.fact_hospital_chargemaster"],"underlying_silver_tables_for_pinning":["vlada_curated.dim_care_site","vlada_curated.fact_hospital_chargemaster","vlada_curated.fact_care_site_grab"],"semantic_views_used":[],"known_gaps":["negotiated_rates_via_lookup_rates_for_npi_not_here","non_ccn_hospital_pricing_pending_hospital_funnel","site_posted_cash_sparse"]},{"name":"compare_hospital_rates","version":"1.0.0","description":"Compares what a billing code costs ACROSS hospitals (cheapest real price first) with a p10/median/p90 benchmark AND a per-(payer x line-of-business) breakdown. The product query for 'where is care cheapest' and 'what does each payer actually pay'. Reads the canonical serving view `vlada_curated.vw_fact_hospital_chargemaster_canonical`, which resolves each raw payer string to its REAL parent entity (the canonical payer graph) and classifies each plan to a regulatory line-of-business (commercial / medicare_advantage / medicaid / marketplace / ...). Inputs: billing_code (required), state (optional 2-letter), code_system (optional), billing_class (default 'institutional' = facility/UB-04; or 'professional'/'both'; classes are never mixed), limit (default 25), payer (optional brand OR parent, e.g. 'Aetna' or 'CVS Health'), line_of_business (optional, e.g. 'medicare_advantage'). Each returned rate carries payer_parent_name + line_of_business so a comparison is apples-to-apples (Aetna-MA != Aetna-Commercial). `value.by_payer_lob` is the 'rates across all the payers' table. CROSS-SUBSTRATE: every rate also carries x_medicare (the multiple of the Medicare allowed amount — PFS national non-facility for professional, OPPS APC for outpatient institutional, IPPS MS-DRG national base for inpatient DRG codes); `value.medicare` holds the allowed amount + schedule + year, so the answer is 'this payer pays 1.6x Medicare at this hospital'. VALIDATION (load-bearing): billing_class is normalized + inferred from code_system/rate_type where the source omits it; only the requested class is compared; class-implausible rates (e.g. $0.007 for a CT) and code-relative outliers are filtered. SOURCE: CMS Hospital Price Transparency MRFs (45 CFR 180.50) + CMS Medicare PFS/OPPS fee schedules. KNOWN GAPS: not geo-aware beyond state; payer resolution covers ~83.5% of volume + LOB ~72.9% (unmatched -> '(unresolved)'/'unspecified'); IPPS DRG x_medicare is the national base (excludes wage index/IME/DSH/outliers); x_medicare null for revenue/non-HCPCS CDM codes; ghost-rate filter is heuristic.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.vw_fact_hospital_chargemaster_canonical"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_fact_hospital_chargemaster_canonical"],"semantic_views_used":[],"known_gaps":["hospital_billing_class_inferred","hospital_geo_state_only","hospital_ghost_rate_filter_heuristic"]},{"name":"compare_hospital_to_commercial","version":"1.0.0","description":"Cross-substrate price comparison for ONE hospital + billing code + payer: lines up THREE prices on one yardstick (Medicare) — (1) the HOSPITAL MRF rate (what the hospital's transparency file lists for that payer), (2) the COMMERCIAL TiC rate (what the payer's OWN file says it pays that provider, resolved by the hospital's NPI through the canonical-graph resolution engine), and (3) the MEDICARE allowed amount. Returns value.hospital_mrf, value.commercial_tic, value.medicare (each with x_medicare), and value.mrf_vs_tic_ratio (the consistency check: ~1 = the two transparency files agree; far from 1 = a setting/plan mismatch or a data-quality signal). Inputs: hospital_ccn (required 6-digit CCN), billing_code (required), payer (required, a commercially-served payer e.g. 'Fallon','Cigna','Highmark','Kaiser'; national brands like Aetna/UnitedHealth aren't extracted commercially yet), state (optional, defaults to the hospital's), code_system, billing_class (optional — by default AUTO-DETECTS the class the hospital actually filed this code under, institutional vs professional). The Medicare benchmark spans PFS (professional) + OPPS/ASC/CLFS/IPPS-DRG (institutional) and falls back across classes since Medicare's schedule is service-driven. ARCHITECTURE: commercial is resolved ON DEMAND, code-bounded, by NPI — NO rate x NPI materialization (the 'Fallon Day' lock; that explodes to 586B rows). Works for the 12 served payers and auto-extends to each new one. COMPARABILITY: prefers provider-specific commercial scope, labels negotiated_type, flags thin-n; x_medicare normalizes across methodologies. SOURCE: CMS Hospital Price Transparency MRFs + payer Transparency-in-Coverage files + CMS Medicare fee schedules.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_medicare_benchmark"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_medicare_benchmark"],"semantic_views_used":[],"known_gaps":["commercial_served_12_payers_only","commercial_org_npi_contracting_entity","hospital_methodology_comparability"]},{"name":"compare_hospital_to_payer_rates","version":"0.1.0","description":"Compare a hospital's published rates to a payer's commercial negotiated rate for one billing code at one hospital (CCN), reading vlada_curated.mart_unified_pricing. Returns each hospital charge type's rate, the payer's commercial rate, and a hospital/commercial ratio + delta ONLY where the two methodologies are compatible (else null with a caveat). Carries source fact-id + source-file provenance.","layer":"L2","domain":"curated","data_sources":["vlada_curated.mart_unified_pricing"],"underlying_silver_tables_for_pinning":["vlada_curated.mart_unified_pricing"],"semantic_views_used":[],"known_gaps":["B1 slice only: mart_unified_pricing currently covers Berkshire Medical Center (CCN 220046) x Fallon, state=MA, ~21 billing codes. Expect sparse/empty results outside that footprint until more (hospital x payer) slices are built."]},{"name":"compare_rates","version":"2.0.0","description":"Return the negotiated rate each of several NPIs is paid for one billing code by one payer in one state, resolved at query time through the canonical graph (no precomputed edge table). payer + state are required for resolution; the NPI list is bounded (25). For a code-level distribution across all providers, use benchmark_code.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["payer + state required","bounded to 25 NPIs per call"]},{"name":"compute_median_rate","version":"1.0.0","description":"Cross-PAYER COMMERCIAL market median for a billing code in a state: the median (+ p10/p90) NEGOTIATED rate ACROSS payers from the commercial Transparency-in-Coverage serving mart (vlada_curated.mart_rate_by_code). Use this for 'what does code X cost across payers / in the market in state Y?'. Requires explicit weighting_method (weighted / unweighted / unique_value); optionally narrow to one payer or negotiated_type (`methodology`). Raises MethodologyConflictError if results span multiple negotiated_type values and the caller didn't narrow with `methodology`. DEFAULTS to the FACILITY (institutional) distribution — facility and professional (physician-fee) rates for a code are different dollars; pass billing_class='all' for the blended view, and the per-billing-class breakdown is always returned. PICK THE RIGHT TOOL: this is the COMMERCIAL cross-payer view — for prices ACROSS HOSPITALS (facility chargemaster) use compare_hospital_rates; for one payer's rate to a specific provider NPI use lookup_rates_for_npi / get_negotiated_rate; for one payer's full distribution use benchmark_code.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.mart_rate_by_code"],"underlying_silver_tables_for_pinning":["vlada_curated.mart_rate_by_code"],"semantic_views_used":[],"known_gaps":[]},{"name":"county_expert","version":"1.0.0","description":"Ask a COUNTY a question and get a reasoned, sourced expert OPINION — the callable geographic healthcare expert other agents consult. Inputs: county_fips (5-digit, e.g. 09001 = Fairfield CT) + question (plain English, e.g. 'where should a Cigna member get an MRI brain?', 'what's the market like?', 'how much is a colonoscopy and where's it cheapest?'). Returns value.answer (the recommendation in words) plus the structured backing — for steerage questions it compares hospital-outpatient rates (from each hospital's own transparency file), posted self-pay prices (grabbed from facility sites), and the Medicare benchmark, then recommends the site-of-care move and quantifies the per-case savings; for market questions it reads supply, consolidation, and payer coverage. Understands procedure names (MRI/colonoscopy/cataract/...) and payers (Cigna/UHC/Aetna/Anthem/...). Composes care_site_price + the HPT + Medicare; every number is source-pinned. A state agent calls this per county; an employer agent calls the counties its workers live in.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster","vlada_curated.vw_medicare_benchmark","vlada_curated.dim_care_site"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster","vlada_curated.fact_care_site_grab","vlada_curated.vw_medicare_benchmark","vlada_curated.dim_care_site"],"semantic_views_used":[],"known_gaps":["non_hospital_negotiated_only_for_built_payers_cigna","deterministic_reasoning_llm_nl_layer_on_top"]},{"name":"county_intelligence","version":"1.0.0","description":"The callable COUNTY EXPERT. Given a 5-digit county FIPS (e.g. 09001 = Fairfield, CT), returns the structured healthcare profile of that county: supply inventory by facility type (hospitals/ASCs/urgent care/imaging/labs/dialysis/...), ownership + consolidation (the health systems present and how many sites each holds), and the TiC payer-coverage summary (how many facilities of each type resolve to each built payer, and the contract shapes). This is the 'tell me about this county' entry a higher-level agent (e.g. a state agent) or an external API caller reasons over. Stateless + FIPS-parameterized: one runtime serves every county. For a specific procedure's options use county_price_options; for one facility's full price use care_site_price. SOURCE: NPPES/CMS registry + the county TiC coverage record.","layer":"L2","domain":"curated","data_sources":["vlada_curated.dim_care_site","vlada_curated.agg_care_site_payer_coverage"],"underlying_silver_tables_for_pinning":["vlada_curated.dim_care_site","vlada_curated.agg_care_site_payer_coverage"],"semantic_views_used":[],"known_gaps":["tic_coverage_only_for_built_payers","physician_practice_tail_unresolved"]},{"name":"county_price_options","version":"1.0.0","description":"Steerage for one procedure in one county. Given a 5-digit county FIPS and a billing_code (CPT/HCPCS), returns the Medicare floor for that code plus — when a `payer` is given — the in-network facilities in the county (from the TiC coverage record) with each facility's contract shape (fee_schedule vs percentage vs in_network_no_rate_in_scope). The 'where can I get this and on what terms' answer a county/state agent uses to steer. Exact per-facility negotiated dollars come from care_site_price(npi, payer, billing_code). Inputs: county_fips (required), billing_code (required), payer (optional). SOURCE: CMS Medicare benchmark + the county TiC coverage record.","layer":"L2","domain":"curated","data_sources":["vlada_curated.vw_medicare_benchmark","vlada_curated.agg_care_site_payer_coverage"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_medicare_benchmark","vlada_curated.agg_care_site_payer_coverage"],"semantic_views_used":[],"known_gaps":["in_network_list_only_for_built_payers","exact_rate_via_care_site_price"]},{"name":"cross_source_rate_distribution","version":"0.1.0","description":"Summarize the rate distribution for one billing code across source types (hospital_gross/cash/.../payer_specific/allowed_amount_* and commercial_negotiated) from vlada_curated.mart_unified_pricing. Returns count/min/median/max per rate_source_type plus an overall rollup. Optional payer_id / state / methodology_normalized filters. Distributions mix methodologies, so cross-source comparison is descriptive only — see compare_hospital_to_payer_rates for methodology-gated ratios.","layer":"L2","domain":"curated","data_sources":["vlada_curated.mart_unified_pricing"],"underlying_silver_tables_for_pinning":["vlada_curated.mart_unified_pricing"],"semantic_views_used":[],"known_gaps":["B1 slice only: mart_unified_pricing currently covers Berkshire Medical Center (CCN 220046) x Fallon, state=MA, ~21 billing codes. Expect sparse/empty results outside that footprint until more (hospital x payer) slices are built."]},{"name":"describe_data_source","version":"1.0.0","description":"Return the full catalog record for one substrate data source: grain, description, row count, freshness SLA, how to query it, provenance chain reference, context doc path, known gaps, and the tools that read it. Accepts a source FQN (e.g. vlada_curated.fact_rate) or its source_id.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"describe_schema","version":"1.0.0","description":"Return the semantic layer in a compact form: marts, columns, invariants, canonical payers, and the list of available tools. Agents call this first to learn the surface at runtime, then invoke specific tools.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"explain_rate","version":"1.0.0","description":"Return a structured, data-backed explanation of a specific rate by rate_id. Includes methodology guidance, lineage (source files), and natural-language summary suitable for UI display.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.mart_rate_by_code"],"underlying_silver_tables_for_pinning":["vlada_curated.mart_rate_by_code"],"semantic_views_used":[],"known_gaps":[]},{"name":"fair_rbp_book","version":"1.0.0","description":"The employer claims-BOOK reference-based-pricing analysis. Input a de-identified set of claim lines (claim_lines; a Limited Data Set, NO PHI — a bill is the lines sharing one claim_id; each line needs hospital_ccn, billing_code, gross_charge, plan_paid, is_inpatient). Reprices every bill greater-of: cost (gross charge x the DEPARTMENT cost-to-charge ratio, HCRIS Worksheet C) x cost_multiplier (default 1.12) vs Medicare x medicare_multiplier (default 1.20), at the legal (bill) grain — outpatient per-line dept CCR, inpatient stay on the overall CCR + DRG. Rolls the book up to value.summary (total_paid, total_fair, total_overpayment, pct_above_fair, concentration_top5_pct, defensible_overpayment), value.strategies (Full / Targeted / rental-only RBP with annual_savings), value.by_hospital, and value.cfo_summary_text (the CFO fiduciary page: the CAA exposure + the recommended strategy). value.bills is the per-bill detail (paid/fair/overpayment/grade/basis). The DEMAND is the caller's; cost / rate / Medicare are ours and source-cited. METHODOLOGY: department CCR (never overall); charge-as-cost sentinel excluded; E&M / professional codes flagged out of scope. KNOWN GAPS: a bill with an unresolved / retired / gross-charge-only code is FLAGGED (summary.n_unresolved_bills) and NOT confidently priced, never guessed; multipliers are illustrative (ELAP) dials. SOURCE: CMS HCRIS Worksheet C + CMS OPPS/IPPS + Hospital Price Transparency MRFs. Vlada is NOT a TPA — evidence, not a payment; it does not adjudicate or litigate.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_medicare_benchmark","medicare_silver.hospital_cost_report_dept","medicare_silver.hcpcs_cost_center_crosswalk"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_medicare_benchmark","medicare_silver.hospital_cost_report_dept","medicare_silver.hcpcs_cost_center_crosswalk"],"semantic_views_used":[],"known_gaps":["hcris_charge_as_cost_sentinel_excluded","hcris_em_professional_out_of_scope","rbp_unresolved_code_flagged_not_priced","rbp_multipliers_illustrative_dials","not_a_tpa_evidence_only"]},{"name":"fair_rbp_price","version":"1.0.0","description":"The reference-based-pricing (RBP) FAIR-PRICE engine: for a facility billing code (optionally one state), returns the COMPLETE cost / rate / Medicare picture no one else joins. Per hospital it computes est_cost = the hospital's gross charge x the DEPARTMENT cost-to-charge ratio for that service's cost center (CMS Medicare cost report / HCRIS Worksheet C) — the actual-cost leg RBP vendors (Imagine360 / ELAP) price against; the Medicare institutional OPPS allowed amount; the fair_rbp_price = GREATER OF (cost x cost_multiplier, default 1.12) and (Medicare x medicare_multiplier, default 1.20); and what payers ACTUALLY pay (our MRF), split into CARRIER vs RENTAL-NETWORK with each as a multiple of actual cost. So the answer is 'a rental network pays 23x the hospital's actual cost for a CT, the carrier pays 6x, a fair RBP price is 1.8x'. Inputs: billing_code (required), state (optional 2-letter), cost_multiplier / medicare_multiplier (optional, default 1.12 / 1.20), limit (default 50). value.summary holds the medians; value.rows the per-(hospital,payer) detail. METHODOLOGY (load-bearing): the DEPARTMENT cost-to-charge ratio, never the hospital overall (CCR spreads ~17x across cost centers; the wrong center overstates low-CCR CT/MRI cost ~10x); the charge-as-cost sentinel (CCR==1.0, NY-concentrated) is EXCLUDED; the code->cost-center map is medicare_silver.hcpcs_cost_center_crosswalk (empirical revenue-code bridge + sub-agent validated). SOURCE: CMS HCRIS 2552-10 Worksheet C + CMS OPPS + Hospital Price Transparency MRFs. KNOWN GAPS: E&M / professional-dominant codes (99xxx) carry a near-1.0 CCR (no facility markup) so there is no cost-plus arbitrage — they are flagged out_of_scope, not priced; ghost rates are filtered code-relative; multipliers are illustrative (ELAP) and vary by contract; cost lags 12-21 months (CCR is a ratio on the current charge so only the ratio is stale).","layer":"L2","domain":"hospital","data_sources":["vlada_curated.vw_fact_hospital_chargemaster_canonical","medicare_silver.hospital_cost_report_dept","medicare_silver.hcpcs_cost_center_crosswalk"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_fact_hospital_chargemaster_canonical","medicare_silver.hospital_cost_report_dept","medicare_silver.hcpcs_cost_center_crosswalk"],"semantic_views_used":[],"known_gaps":["hcris_charge_as_cost_sentinel_excluded","hcris_em_professional_out_of_scope","hcris_cost_report_lag_12_21mo","hospital_ghost_rate_filter_heuristic"]},{"name":"fetch_query","version":"1.0.0","description":"Fetch the result of an async job once it is done. Returns the wrapped tool's full response when status is done; a not_ready caveat while it is still queued/running; or the error when it failed.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"find_data_sources","version":"1.0.0","description":"Search the Vlada substrate catalog by keyword. Returns the matching data sources (commercial TiC, hospital HPT, Medicare, drug pricing, provider identity, curated marts, provenance registries) ranked by relevance, each with its domain, stage, grain, query surface, and context doc. Optional filters: {domain, stage, status, limit}. Agents call this first to discover what data Vlada has.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"get_hospital_chargemaster","version":"1.0.0","description":"Returns chargemaster rate data for a US hospital (by 6-digit CMS Certification Number) with byte-level audit trail. Reads from `vlada_curated.fact_hospital_chargemaster` filtered to the dynamic verified cohort by default. Each response carries `sha256_content_hash`, `bronze_object_key`, `mrf_version_id`, and `source_url` for the underlying MRF — agents quoting a rate can substantiate it to the original bytes. GRAIN: (hospital_ccn, billing_code, payer_name, plan_name). When `billing_code` is omitted, returns a row-count summary instead of full rate rows (cheap metadata query). CANONICAL PAYER: each rate row also carries `payer_canonical_id`, `payer_display`, `line_of_business` (commercial | medicare_advantage | medicaid_managed | tricare | unknown), and `payer_unresolved`, resolved from the hospital's raw payer_name/plan_name via the alias registry in semantic/payers.yaml — the raw payer_name/plan_name are always preserved verbatim alongside them. SOURCE: CMS Hospital Price Transparency MRFs (45 CFR §180.50). VERIFIED COHORT (dynamic): every CCN with a curated version in RDS (curated_version IS NOT NULL, not quarantined) — ~719 CCNs as of 2026-05-17 and growing weekly via the Path-to-75 drain (the original 3-CCN allowlist was lifted 2026-05-17). Non-cohort CCNs return `data_gated` with `gap_id=hospital_audit_chain_incomplete` unless `audit_tier_filter` is set to include `partial` or `all`. A curated legacy CCN returns rows under the default filter because it is in the cohort — that is the gate passing, not a bypass. KNOWN GAPS: hospital_audit_chain_incomplete (legacy 2,374 CCNs); hospital_billing_class_hardcoded (institutional ratios pending); hospital_ghost_rate_filter_disabled (validator pre-F.B/F.C). UNVERIFIED — do not rely on: cross-hospital DRG / inpatient surgery comparability (institutional billing_class match not enforced); intracompany payer-provider rate filter (HOSP-3-LITE shipped but not yet wired into this tool — Phase F.F).","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":["hospital_audit_chain_incomplete","hospital_billing_class_hardcoded","hospital_ghost_rate_filter_disabled"]},{"name":"get_negotiated_rate","version":"2.0.0","description":"Get the negotiated rate a specific payer pays a specific NPI for a specific billing code, in a state. Resolves at query time through the canonical graph + inverted indexes (no precomputed edge table) and returns the most provider-specific rate with source lineage, methodology, evidence type, and Medicare-PUF corroboration. UHC custom codes are resolved automatically. Covers all built payers.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["state required for resolution","medical_mutual not yet indexed"]},{"name":"get_rate_with_provenance","version":"1.0.0","description":"Get the negotiated rate a payer pays an NPI for a billing code, bundled with its provenance and a replay/proof pointer. Wraps the proven get_negotiated_rate lookup (payer-alias resolution, UHC code crosswalk, ghost-rate filter, outlier flag, snapshot-pinned read) and returns the rate value, source table + Iceberg snapshot, rate_id, source files, quality flags, the upstream response hash, caveats, a replay_pointer that re-runs the exact lookup, and a proof_pointer to prove_commercial_price when state + vintage are known. This is the Product 1 'give me the rate and the receipt' entry point.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["state required for resolution"]},{"name":"lookup_rates_for_npi","version":"1.0.0","description":"Look up the negotiated rates a payer pays a specific provider (NPI), resolved at query time through the canonical graph: NPI → provider groups → pg_sets → rates (no precomputed edge table). Returns matching rates with evidence_type (provider_specific vs broad applicability) and Medicare-PUF corroboration (presence ⇒ real; absence ⇒ unverified, NOT ghost). Optional code filter. Covers all built payers.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_npi_provider_group","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["medical_mutual not yet indexed"]},{"name":"lookup_rates_for_tin","version":"1.0.0","description":"Look up the negotiated rates a payer attaches to a tax entity (TIN/EIN), resolved at query time through the canonical graph: TIN → provider groups (idx_tin_provider_group) → pg_sets → rates. Accepts hyphenated EINs (normalized digits-only 9). Every result carries provenance: tin_business_name (the payer-asserted entity name), tin_scope_class (fanout class), and tin_index_path ('membership' = payer-asserted NPI↔TIN rows; 'bridge' = system-level group evidence). A TIN is system-shared, NOT building-exact — use lookup_rates_for_npi first for building-specific evidence; this is the fallback rung of the facility identity ladder. Payers without a TIN index (e.g. carefirst-class, no usable EIN rows) return an honest empty.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate","vlada_curated.idx_rate_lookup"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate","vlada_curated.idx_tin_provider_group","vlada_curated.idx_rate_lookup"],"semantic_views_used":[],"known_gaps":["TIN evidence is system-shared, not building-exact","carefirst-class payers (NPI stuffed into tin_value) have no TIN index"]},{"name":"plan_answerability","version":"1.0.0","description":"Plan whether Vlada can answer a user's healthcare data question before running SQL or a specialized tool. Returns yes/partial/no, the required source-product cards, visible/queryable/certified/data_proven rungs, unsafe assumptions to avoid, and the suggested MCP tool sequence. Agents call this when they ask 'can Vlada answer this?'","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"plan_commercial_price_proof","version":"1.0.0","description":"Dry-run a bounded commercial fact_rate proof. Requires payer, version_id, state, and code. Plans Iceberg files/bytes before materializing rows, and returns a receipt-shaped plan. On no_match (version_id not found) the value includes `available_versions`: the version_ids that do carry rows for that payer/state/code, so an agent can pick a valid one. version_ids are payer-scoped strings, not bare YYYY-MM.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate"],"semantic_views_used":[],"known_gaps":[]},{"name":"plan_hospital_price","version":"1.0.0","description":"Dry-run a bounded hospital fact_hospital_chargemaster proof. Requires hospital_ccn and billing_code, plans Iceberg files/bytes before materializing rows, and returns a receipt-shaped plan.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[]},{"name":"poll_query","version":"1.0.0","description":"Poll the status of an async job submitted with submit_query. Returns queued/running/done/error and whether it is terminal. When done, read the result with fetch_query.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"prove_commercial_price","version":"1.0.0","description":"Execute a bounded commercial fact_rate price proof and return rate summary values plus a receipt with source snapshot, filters, row count, caveats, input hash, response hash, and replay pointer. On no_match (version_id not found) the value includes `available_versions`: the version_ids that do carry rows for that payer/state/code, so an agent can pick a valid one and re-run.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate"],"semantic_views_used":[],"known_gaps":[]},{"name":"prove_hospital_price","version":"1.0.0","description":"Execute a bounded hospital chargemaster price proof and return rate summary values plus a receipt with source snapshot, filters, raw byte provenance, caveats, input hash, response hash, and replay pointer.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[]},{"name":"query","version":"0.1.0","description":"SAFE STUB. Given a catalog source FQN, return how to query it — the query surface (Athena FQN, tool name, or S3 path) and an example approach — WITHOUT executing arbitrary production SQL. Use the typed tools (get_negotiated_rate, get_hospital_chargemaster, …) or Athena directly for real reads. Execution is intentionally not enabled here.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"query_substrate","version":"1.0.0","description":"Run a read-only SQL SELECT directly over the Vlada cost-data substrate (Athena/Iceberg) and get the rows back, with provenance. Use this when the pre-built tools don't answer your exact question. WORKFLOW: first call find_data_sources / describe_data_source to find the table + read its card (grain, columns, and the CAVEATS you must apply — e.g. filter ghost rates, never blend across modifiers/methodologies), THEN write SQL against the table's fully-qualified name (e.g. vlada_curated.fact_hospital_chargemaster). RULES: read-only SELECT only (no INSERT/UPDATE/DDL — rejected); you may only query tables your account is entitled to (others are rejected); results are LIMIT-bounded and the scan is cost-capped. Every result carries provenance (the engine, query id, bytes scanned, tables read). Apply the source card's methodology yourself — raw SQL does not enforce it.","layer":"L1","domain":"commercial","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Raw SQL does NOT enforce a source's methodology (ghost-rate filter, modifier/methodology non-blending) — the agent must apply the caveats from the source card. For warranted, methodology-enforced numbers use the source's specialized tool."]},{"name":"replay_commercial_price_proof","version":"1.0.0","description":"Replay a commercial price-proof receipt by re-running its recorded tool inputs and comparing response hash, Iceberg snapshot, plan hash, status, and row count.","layer":"L2","domain":"commercial","data_sources":["vlada_curated.fact_rate"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_rate"],"semantic_views_used":[],"known_gaps":[]},{"name":"replay_hospital_price","version":"1.0.0","description":"Replay a hospital price-proof receipt by re-running its recorded tool inputs and comparing response hash, Iceberg snapshot, plan hash, row count, status, and raw-byte source descriptor.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[]},{"name":"search_tools","version":"1.0.0","description":"Find the right tool for a task. Given a natural-language description of what you want to do, returns the best-matching tools (name, description, parameters) ranked by relevance — so you can DISCOVER the correct specialized tool instead of scanning the whole catalog. Use this FIRST when you're unsure which tool fits (e.g. 'analyze PBM spread', 'reprice a hospital bill', 'compare MA plan benefits'); then call the tool it points you to. Only returns tools you are entitled to call. This is a DISCOVERY helper — it does not answer the question itself, it tells you which tool will.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Keyword/relevance ranking over tool name + description — not semantic embedding. Describe the task in domain terms (e.g. 'negotiated rate', 'reprice', 'formulary') for the best matches."]},{"name":"state_agent","version":"1.0.0","description":"The apex callable STATE EXPERT — a complete, DOCUMENT-GROUNDED read on a US state's healthcare. Given a 2-letter state code (e.g. 'CT') and an optional question, returns: (1) DATA AVAILABILITY (hospitals priced, rows, codes, sites, payers from the curated substrate); (2) the EFFECTIVE POLICY — the national federal baseline (HPT rule, TiC rule, ERISA/Gobeille, No Surprises Act) PLUS the state overlay (e.g. CT's APCD, cost-growth benchmark, CON, surprise-bill law) PLUS the INTERPLAY edges that show how they interact (federal_constrains_state, federal_defers_to_state, state_adds, state_overrides); (3) the DOCUMENT CORPUS backing every claim (federal + state, with citations + source URLs); (4) the PRICING REGIME and DATA REGIME that configure how the numbers must be read (so a rate-setting state like MD is never graded like a negotiated state, and the APCD self-funded/ERISA hole is stated explicitly); and (5) the GAPS, including structural policy constraints. The state is a LENS + a policy OVERLAY on the one national substrate, not a silo — everything is national-rooted and the value is the national<->state interplay. Every number traces to the substrate; every policy claim traces to a public document. Drill into a county with county_intelligence; into a facility with care_site_price. SOURCE: curated hospital chargemaster + care-site registry + the document-grounded policy graph.","layer":"L2","domain":"hospital","data_sources":["vlada_curated.fact_hospital_chargemaster","vlada_curated.dim_care_site"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster","vlada_curated.dim_care_site"],"semantic_views_used":[],"known_gaps":["policy_graph_is_inline_seed_not_yet_dim_document_dim_policy","document_corpus_curated_initial_set_not_exhaustive","freshness_not_yet_tracked_pending_refresh_cascade"]},{"name":"state_expert","version":"1.0.0","description":"The callable STATE EXPERT — the data-availability + regulation X-ray for a US state. Given a 2-letter state code (e.g. 'CT'), returns: (1) DATA AVAILABILITY — how many hospitals are priced, total price rows, distinct billing codes, care sites mapped, and payers with resolved coverage; (2) the REGULATION object — the rules of the game in that state (transparency regime, required disclosures, public datasets like an APCD or rate-setting authority, and the completeness bar); and (3) the computed GAPS — required-or-known datasets we have NOT yet ingested (e.g. a mandatory APCD), so absence is reported as gap-vs-expected, not silently. This is the 'what data do we have in this state, what is required here, and what is missing' entry a higher-level agent or operator reasons over. Because hospital pricing is a NATIONAL substrate, a state can show many hospitals priced even before its county map is built (e.g. MD). Stateless + state-parameterized: one runtime serves every state. Drill into a county with county_intelligence; into one facility with care_site_price. SOURCE: curated hospital chargemaster + care-site registry + the state-regulation object.","layer":"L2","domain":"curated","data_sources":["vlada_curated.fact_hospital_chargemaster","vlada_curated.dim_care_site","vlada_curated.agg_care_site_payer_coverage"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster","vlada_curated.dim_care_site","vlada_curated.agg_care_site_payer_coverage"],"semantic_views_used":[],"known_gaps":["regulation_object_is_seed_not_yet_dim_state_regulation","freshness_not_yet_tracked_pending_refresh_cascade","county_map_built_for_CT_only"]},{"name":"state_ingest","version":"1.0.0","description":"REASON about and EXECUTE data ingestion for a state — the engine that turns the data-source universe from 'available' into 'ingested'. With only a state_code, returns the prioritized INGESTION PLAN: every not-yet-ingested source with its method (open_api / open_bulk / portal_request / dua_purchase), target table, cadence, and whether it is runnable now vs gated (and what unblocks it). With a `source` name, EXECUTES that ingestion: open-API sources (e.g. 'CDC PLACES') are pulled LIVE and return structured records + a provenance receipt; gated sources (e.g. the state APCD, HCUP) return the access plan instead. This is how the state agent widens its own coverage and how refresh(place) fills open domains (claims, outcomes, quality, workforce, financial). Every ingested fact carries its source + endpoint. Inputs: state_code (required), source (optional). SOURCE: the open public-health/health-system data APIs named in the plan.","layer":"L2","domain":"hospital","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["open_api_ingesters_implemented_for_cdc_places_others_planned","ingested_records_not_yet_landed_in_athena_dim_tables"]},{"name":"submit_query","version":"1.0.0","description":"Submit a heavy/long-running query to run OFF the request path and get a job_id back immediately, instead of blocking (and risking a timeout) on a statewide/cross-hospital scan. Use for compare_hospital_rates and query_substrate; point-lookup tools should be called directly. Poll with poll_query(job_id) and read the result with fetch_query(job_id).","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]}]}