{"ok":true,"catalog":{"version":"1.0","generated_at":"2026-09-24T16:31:49.743140+00:00"},"query":{"view":"all","q":null,"domain":null,"status":null},"summary":{"total_sources":417,"total_tools":44,"sources_by_domain":{"commercial":48,"hospital":16,"provider_identity":40,"medicare":208,"drug":46,"curated":18,"provenance":5,"state":36},"sources_by_stage":{"semantic_view":43,"silver":286,"curated":7,"mart":12,"index":1,"dim":57,"raw":3,"reference":3,"registry":5},"sources_by_status":{"live":328,"planned":18,"partial":55,"retired":13,"design_locked":2,"blocked":1},"sources_with_documented_row_count":226,"tools_linked_to_a_source":32,"tools_unlinked":12,"tools_by_layer":{"L2":39,"L1":5},"warnings_count":8,"live_inspection":{"glue_available":false,"postgres_available":false}},"warnings":["`known_gaps` differs between assets of the same dataset in 54 dataset(s); left on the asset. Assets that disagree about known_gaps may not belong to one source.","`recollection` differs between assets of the same dataset in 50 dataset(s); left on the asset. Assets that disagree about recollection may not belong to one source.","`freshness_sla` differs between assets of the same dataset in 48 dataset(s); left on the asset. Assets that disagree about freshness_sla may not belong to one source.","`commercial_terms` differs between assets of the same dataset in 27 dataset(s); left on the asset. Assets that disagree about commercial_terms may not belong to one source.","`provenance_chain_ref` differs between assets of the same dataset in 26 dataset(s); left on the asset. Assets that disagree about provenance_chain_ref may not belong to one source.","`context_doc_path` differs between assets of the same dataset in 24 dataset(s); left on the asset. Assets that disagree about context_doc_path may not belong to one source.","live inspection disabled via --no-live","7 of 194 join edge(s) are unvalidated and 158 have passed; no cross-source tool may be generated from an unvalidated edge (run ops/scripts/validate_join_edges.py)."],"domains":{"commercial":{"source_count":48,"tool_count":8,"sources":["medicare_semantic.vw_plan_attributes_puf_current","medicare_semantic.vw_benefits_cost_sharing_current","medicare_semantic.vw_plan_id_crosswalk_puf_current","medicare_silver.fact_machine_readable_url_puf_history","cms_transparency_qhp_coverage_puf","cms_marketplace_quality_puf","medicare_silver.fact_nationwide_qrs_puf_history","medicare_silver.fact_enrollee_survey_puf_history","medicare_semantic.vw_service_area_puf_current","medicare_semantic.vw_network_puf_current","medicare_semantic.vw_business_rules_puf_current","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","insurer_silver.fact_insurer_mlr","insurer_silver.dim_insurer_mlr_identity","medicare_silver.fact_transparency_in_coverage_puf_history","medicare_silver.fact_quality_puf_history","medicare_silver.fact_exchange_plan_profile","medicare_silver.fact_idr_air_ambulance_determination","medicare_silver.fact_idr_qpa_offer","medicare_silver.fact_idr_supplemental_summary","medicare_silver.fact_idr_supplemental_state","medicare_silver.fact_idr_supplemental_party","medicare_silver.fact_idr_supplemental_qpa_band","medicare_silver.fact_idr_supplemental_specialty","medicare_silver.fact_marketplace_plan_enrollment_measure_history","medicare_silver.fact_marketplace_issuer_geography_enrollment_measure_history","medicare_silver.fact_marketplace_monthly_effectuated_enrollment_history","ga_georgia_access_puf","va_vim_enrollment_metrics","ky_khbe_governors_metrics","ca_covered_california_enrollment_profiles","nj_getcoverednj_enrollment","nj_dobi_ihc_enrollment","wa_hbe_enrollment_reports","ny_nysoh_enrollment_data","vt_vhc_data_surfaces","ar_aid_marketplace_surfaces","medicare_silver.dim_hix_temporal_identity_bridge","medicare_gold.mart_hix_*"],"tools":["get_exchange_plan_profile","get_negotiated_rate","lookup_rates_for_npi","lookup_rates_for_tin","plan_commercial_price_proof","prove_commercial_price","query_substrate","replay_commercial_price_proof"]},"curated":{"source_count":18,"tool_count":11,"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","vlada_curated.dim_hcpcs","vlada_curated.dim_state"],"tools":["certified_measure","describe_data_source","describe_schema","fetch_query","find_data_sources","how_to_join","poll_query","query","search_tools","state_expert","submit_query"]},"drug":{"source_count":46,"tool_count":8,"sources":["drug_silver.fact_drug_acquisition_cost","drug_silver.fact_drug_asp_quarterly#drug_asp","drug_silver.fact_drug_asp_quarterly","drug_silver.fact_asp_ndc_hcpcs_crosswalk","drug_silver.fact_form5500_insurance","drug_silver.fact_form5500_insurance_broker","drug_silver.fact_form5500_financials","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":["asp_pricing_lookup","excluded_prescriber_payment_screen","formulary_churn","get_drug_source_inventory","ira_drug_label_risk_screen","ira_mfp_exposure","pbm_compensation_rollup","recall_spend_window"]},"hospital":{"source_count":16,"tool_count":6,"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","medicare_silver.fact_hacrp"],"tools":["compare_hospital_rates","coverage_status","get_hospital_quality","plan_hospital_price","prove_hospital_price","replay_hospital_price"]},"medicare":{"source_count":208,"tool_count":10,"sources":["medicare_silver.fact_pfs_rvu","medicare_silver.fact_opps_addendum_b","drug_silver.dim_msdrg","medicare_silver.fact_asc_addendum","medicare_silver.medicare_clfs_rates","medicare_silver.fact_clfs_national_rate","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.fact_ma_mlr","medicare_silver.hospital_cost_report_overall","medicare_silver.hospital_cost_report_dept","medicare_silver.facility_cost_report_unit","medicare_silver.fact_facility_cost_report_unit","medicare_silver.facility_cost_report_ccr","medicare_silver.fact_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.fact_ma_landscape","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","medicare_silver.fact_ipps_wage_index","medicare_silver.fact_dme_payment_by_geo","medicare_silver.fact_physician_payment_by_geo","medicare_silver.fact_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.ma_landscape_member_ledger","medicare_silver.fact_ma_landscape_edition","medicare_silver.ma_landscape_edition_ledger","medicare_silver.mpf_optional_supplemental_annual","medicare_silver.fact_medicare_geo_variation","medicare_silver.fact_esrd_qip","medicare_silver.ncci_ptp","medicare_silver.ref_ncci_ptp_edit","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_clfs_private_payer_rate_2026collection","medicare_silver.fact_clfs_preliminary_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","medicare_silver.hospital_cost_report_utilization","medicare_silver.hospital_cost_report_financial","medicare_silver.hospital_cost_report_profile","medicare_silver.hospital_cost_report_report","medicare_silver.hospital_cost_report_numeric_cell","medicare_silver.hospital_cost_report_alpha_cell","medicare_silver.hospital_cost_report_payer_revenue","medicare_silver.mcd_document","medicare_silver.mcd_document_relationship","medicare_silver.mcd_document_component","medicare_silver.mcd_reference","medicare_silver.resdac_claim_reference_source_asset","medicare_silver.resdac_claim_code","medicare_silver.resdac_specialty_taxonomy_crosswalk","medicare_silver.x12_code_list_asset","medicare_silver.ahrq_source_asset","medicare_silver.ahrq_ccsr_mapping","medicare_silver.ahrq_ccsr_category","medicare_silver.ahrq_qi_value_set","medicare_silver.ahrq_qi_benchmark","medicare_silver.medpac_databook_source_asset","medicare_silver.medpac_databook_page","medicare_silver.medpac_databook_workbook_cell","medicare_silver.medpac_databook_exhibit","medicare_silver.medpac_databook_metric_observation","medicare_silver.fact_medicaid_core_set_quality","medicare_silver.ipps_payment_source_asset","medicare_silver.ipps_impact_provider_row","medicare_silver.inpatient_psf_provider_record","medicare_silver.qualitynet_methodology_source_asset","medicare_silver.qualitynet_methodology_document","medicare_silver.qualitynet_methodology_document_text","medicare_silver.qualitynet_methodology_table_row","medicare_silver.cssc_operations_source_asset","medicare_silver.cssc_operations_resource","medicare_silver.cssc_operations_attachment","medicare_silver.cssc_operational_edit","medicare_silver.cssc_acceptable_specialty","medicare_silver.cssc_sbsc_code","medicare_silver.fact_ahrq_nhqdr_quality","medicare_semantic.vw_state_quality_publisher","medicare_semantic.vw_state_quality_rollup","vlada_curated.dim_contract","medicare_silver.fact_pfs_gpci_locality","medicare_silver.fact_pfs_locality_config","medicare_semantic.vw_plan_value_national","medicare_semantic.vw_plan_value_county","medicare_semantic.benvat_v1_plan_county","medicare_semantic.benvat_county_v1"],"tools":["get_enrollment","get_hos","get_landscape","get_market_share","get_medicaid_mco_enrollment","get_pbp_benefit","get_stars","get_stars_cutpoints","medicare_allowed","prove_ma_enrollment_trend"]},"provenance":{"source_count":5,"tool_count":0,"sources":["dim_substrate_mrf_version","medicare_source_registry_cache","drug_source_registry_cache","dim_mrf_version","medicare_silver.hix_state_artifact_revision_history"],"tools":[]},"provider_identity":{"source_count":40,"tool_count":1,"sources":["vlada_curated.provider_facility_xref","s3://vlada-platform-raw/nppes","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","vlada_curated.dim_provider_ccn"],"tools":["resolve_provider"]},"state":{"source_count":36,"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","medicare_silver.macpac_macstats_source_asset","medicare_silver.macpac_macstats_page","medicare_silver.macpac_macstats_workbook_cell","medicare_silver.macpac_macstats_exhibit","medicare_silver.macpac_macstats_metric_observation","medicare_silver.fact_cdc_nhsn_state_hai","medicare_silver.fact_medicaid_health_home_quality","medicare_silver.cms_medicaid_chip_enrollment_source_asset","medicare_silver.cms_medicaid_chip_enrollment_workbook_cell","medicare_silver.cms_medicaid_chip_enrollment_monthly_state","medicare_silver.cms_medicaid_managed_care_plan_source_asset","medicare_silver.cms_medicaid_managed_care_plan_enrollment","medicare_silver.fact_ca_medi_cal_managed_care_enrollment","medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v2","medicare_silver.ca_calaim_1915b_source_occurrence","medicare_silver.ca_calaim_1915b_pdf_page","medicare_silver.ca_calaim_1915b_workbook_cell","medicare_silver.ca_medi_cal_managed_care_contract_source_occurrence","medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot","medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot_text","medicare_silver.ca_medi_cal_managed_care_contract_pdf_page","medicare_silver.ca_medi_cal_mcp_roster_source_occurrence","medicare_silver.ca_medi_cal_mcp_roster_pdf_page","medicare_silver.ca_medi_cal_mcp_county_plan_roster","medicare_silver.ca_smhs_1915b_legacy_history_period","medicare_silver.ca_smhs_1915b_legacy_source_occurrence","medicare_silver.ca_smhs_1915b_legacy_pdf_page"],"tools":[]}},"counts":{"sources":417,"tools":44},"sources":[{"source_id":"cms_plan_attributes_puf","source_fqn":"medicare_semantic.vw_plan_attributes_puf_current","title":"CMS CCIIO Plan Attributes PUF — Marketplace plan definition history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One logical publisher CSV record within one immutable (business_year, source_zip_sha256, archive_member) artifact, keyed by one-based source_row_number.","description":"CMS Marketplace plan-variant definitions and the central bridge among issuers, products, networks, service areas, benefits, and rates across PY2014-PY2026. All raw publisher revisions are retained; no semantic current-plan winner is selected.","identity_key":"source_id,business_year,source_zip_sha256,archive_member,source_row_number","row_count":null,"last_updated":"2026-07-15","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_plan_attributes_puf_history has not been created or loaded.","notes":"The source bytes contain 300,992 certified logical rows across 13 annual ZIPs and seven exact ordered-header schema eras; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_plan_attributes_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["archive_member","business_year","source_id","source_row_number","source_zip_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_benefits_cost_sharing_puf","source_fqn":"medicare_semantic.vw_benefits_cost_sharing_current","title":"CMS CCIIO Benefits & Cost Sharing PUF — Marketplace benefit-template history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One publisher benefit row of the current selected revision, keyed by (business_year, plan_id, benefit_name, source_row_number). A plan may list the same benefit more than once (e.g. per tier or cost-sharing variant); every such row is preserved — no plan/benefit collapse. The underlying physical history remains one row per source, year, member SHA-256, archive member, and source-row ordinal across all revisions.","description":"CMS Marketplace plan-variant benefit, coverage, raw cost-sharing, limit, exclusion, EHB-variance, and MOOP-exclusion text across PY2014-PY2026. The served view selects the latest reviewed revision for each business year and maps each era's ordered raw-cell array to named raw-text columns without amount parsing or blank-to-zero coercion.","identity_key":"business_year,plan_id,benefit_name,source_row_number","row_count":19692051,"last_updated":"2026-07-17","raw_queryable_via":"query_substrate (read-only SQL) over medicare_semantic.vw_benefits_cost_sharing_current. Revision-history access to medicare_silver.fact_benefits_cost_sharing_puf_history requires a separate operator-approved entitlement.","notes":"The physical history table contains 45,082,577 rows across PY2014-PY2026 and all reviewed revisions; the served view surfaces the 19,692,051-row current selection. The served view maps 32-column PY2014-PY2015 display headers, the 30-column PY2016 compact header, and the 24-column PY2017-PY2026 header through ordered_header_json plus raw_values_json. The view DDL is deployed to medicare_semantic and count-verified (2026-07-17); this change entitles the served FQN.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_benefits_cost_sharing_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:plan_id"],"entity_key_columns":{"cms:plan_id":["plan_id"]},"technical_keys":["business_year","source_row_number"],"unmapped_key_tokens":["benefit_name"],"backing_store":"glue"},{"source_id":"cms_plan_id_crosswalk_puf","source_fqn":"medicare_semantic.vw_plan_id_crosswalk_puf_current","title":"CMS CCIIO Plan ID Crosswalk PUF — directed plan-year continuity history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One logical publisher CSV record within one immutable directed current-plan-year artifact, keyed by source, current year, ZIP SHA-256, archive member, and one-based source row number.","description":"CMS Marketplace standard-component continuity from plan year N-1 to N across PY2014→2015 through PY2025→2026, preserving ordinary, age-off, and bronze-to-silver publisher fields without projecting semantic routes.","identity_key":"source_id,current_plan_year,source_zip_sha256,archive_member,source_row_number","row_count":null,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_plan_id_crosswalk_puf_history has not been created or loaded.","notes":"The source bytes contain 1,649,072 certified logical rows across 12 directed annual ZIPs and 12 exact annual headers; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_plan_id_crosswalk_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["archive_member","source_id","source_row_number","source_zip_sha256"],"unmapped_key_tokens":["current_plan_year"],"backing_store":"glue"},{"source_id":"cms_machine_readable_url_puf","source_fqn":"medicare_silver.fact_machine_readable_url_puf_history","title":"CMS CCIIO Machine Readable URL PUF — restricted issuer URL assertion history","domain":"commercial","stage":"silver","status":"live","grain":"One nonempty publisher worksheet row within one immutable ZIP/XLSX artifact, keyed by source, plan year, ZIP SHA-256, archive member, and one-based logical source row number.","description":"CMS-published issuer/state assertions of submitted machine-readable index URLs for PY2016-PY2026, including eight recovered prior artifact revisions. Technical point-of-contact fields remain restricted; submitted URLs are inert values and linked issuer JSON is a separate source lane.","identity_key":"source_id,plan_year,source_zip_sha256,archive_member,source_row_number","row_count":null,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_hix_machine_readable_url_puf_history has not been created or loaded.","notes":"The certified bytes contain 7,071 logical rows across 19 distinct CMS/Wayback artifacts—11 live annual releases and eight prior revisions—plus five official PDFs; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_machine_readable_url_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["archive_member","plan_year","source_id","source_row_number","source_zip_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_transparency_qhp_coverage_puf","source_fqn":"cms_transparency_qhp_coverage_puf","title":"CMS CCIIO Transparency in QHP Coverage PUF — lossless multi-grain workbook history","domain":"commercial","stage":"silver","status":"planned","grain":"One publisher data row within one worksheet of one immutable ZIP/workbook artifact, keyed by source, publication year, ZIP SHA-256, archive member, worksheet, and one-based logical source row number.","description":"CMS federal-Marketplace issuer- and plan-level claims, appeals, enrollment, disenrollment, and financial-information fields across PY2017-PY2026. Sixteen accepted current/Wayback XLSX artifacts contain 68,879 revision-qualified rows; one earlier byte-certified BIFF8 XLS has 398 candidate rows whose row adapter remains gated.","identity_key":"source_id,publication_year,source_zip_sha256,archive_member,worksheet_name,source_row_number","row_count":null,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_tc_puf_history has not been created or loaded.","notes":"Accepted XLSX source history contains 68,879 revision-qualified rows across 16 artifacts; the 17th artifact is a byte-certified legacy XLS with 398 gated candidate rows. row_count is null because no production table exists. The live cms_tc_puf_issuer_claims source remains a separate 25,666-row partial derivative.","superseded_by":null,"tools":[],"dataset_id":"ds_cms_transparency","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["archive_member","source_id","source_row_number","source_zip_sha256"],"unmapped_key_tokens":["publication_year","worksheet_name"],"backing_store":"logical_not_ingested"},{"source_id":"cms_marketplace_quality_puf","source_fqn":"cms_marketplace_quality_puf","title":"CMS Marketplace Quality PUF — federal-platform display rating history","domain":"commercial","stage":"silver","status":"planned","grain":"One nonblank publisher plan row within one immutable annual ZIP or direct-XLSX artifact, keyed by source, display publication year, container SHA-256, data object, and one-based logical source row number.","description":"CMS federal-Marketplace plan display star ratings across PY2017-PY2026, preserving six exact schema eras, reporting-unit repetition, raw year-specific not-rated lexemes, pilot/platform scope, and honest direct-XLSX lineage.","identity_key":"source_id,publication_year,source_container_sha256,data_object_name,source_row_number","row_count":null,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_marketplace_quality_puf_history has not been created or loaded.","notes":"Ten exact official artifacts contain 35,752 source rows; nine exact-URL Wayback captures are byte-equal to live and create no additional revisions. row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"ds_cms_marketplace","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id","source_row_number"],"unmapped_key_tokens":["data_object_name","publication_year","source_container_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"cms_nationwide_qrs_puf","source_fqn":"medicare_silver.fact_nationwide_qrs_puf_history","title":"CMS Nationwide QRS PUF — Exchange reporting-unit quality history","domain":"commercial","stage":"silver","status":"live","grain":"One publisher reporting-unit row within one immutable annual CSV data unit, keyed by publication plan year, CSV SHA-256, and one-based source row number; container revisions are retained separately.","description":"CMS Nationwide Quality Rating System results across PY2019-PY2026 at issuer-state-product-type reporting-unit grain, preserving seven exact schema eras, ratings-year semantics, raw field-qualified publisher codes, dictionary matrices, and container-versus-data-unit revision identity.","identity_key":"source_id,publication_plan_year,csv_sha256,source_row_number","row_count":871,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_nationwide_qrs_puf_history has not been created or loaded.","notes":"Eight current official ZIPs and one distinct recovered PY2023 container revision produce eight unique CSV data units and 1,986 rows. The recovered PY2023 CSV is byte-identical to live, so its container and dictionary lineage coexist while its fact rows are a physical no-op. row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_nationwide_qrs_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id","source_row_number"],"unmapped_key_tokens":["csv_sha256","publication_plan_year"],"backing_store":"glue"},{"source_id":"cms_enrollee_survey_puf","source_fqn":"medicare_silver.fact_enrollee_survey_puf_history","title":"CMS QHP Enrollee Survey PUF — nationwide reporting-unit survey history","domain":"commercial","stage":"silver","status":"live","grain":"One publisher wide row within one immutable year-qualified data unit, with mandatory row_kind separating issuer-state-product reporting units from the annual National row; container revisions are retained separately.","description":"CMS nationwide Exchange enrollee-experience results for PY2022-PY2026, preserving publication year, survey year, prior experience period, four exact ordered-header eras, incomplete/missing dictionary provenance, raw blank/dot/count/score semantics, and container-versus-data-unit revision identity.","identity_key":"source_id,publication_plan_year,data_sha256,source_row_number","row_count":748,"last_updated":"2026-07-16","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_hix_enrollee_survey_puf_history has not been created or loaded.","notes":"Five current official ZIPs plus one distinct pre-508 PY2022 container revision produce five unique data units and 1,586 rows. The two PY2022 CSVs are byte-identical, so both document/container lineages coexist while their fact rows are a physical no-op. row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_enrollee_survey_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id","source_row_number"],"unmapped_key_tokens":["data_sha256","publication_plan_year"],"backing_store":"glue"},{"source_id":"cms_service_area_puf","source_fqn":"medicare_semantic.vw_service_area_puf_current","title":"CMS CCIIO Service Area PUF — Marketplace plan geography history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One logical publisher CSV record within one immutable (business_year, source_zip_sha256) artifact, keyed by archive member and one-based source_row_number.","description":"CMS Marketplace issuer service-area geography across PY2014-PY2026, including entire-state, county, and publisher-supplied partial-county ZIP rules. Historical templates are versioned; this planned source does not select a current revision.","identity_key":"business_year,source_zip_sha256,archive_member,source_row_number","row_count":null,"last_updated":"2026-07-15","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_service_area_puf_history has not been created or loaded.","notes":"The source bytes contain 158,759 certified logical rows across 13 annual ZIPs and five representation eras; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_service_area_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["archive_member","business_year","source_row_number","source_zip_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_network_puf","source_fqn":"medicare_semantic.vw_network_puf_current","title":"CMS CCIIO Network PUF — issuer network metadata history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One logical publisher CSV record within one immutable (business_year, source_zip_sha256) artifact, keyed by one-based source_row_number.","description":"CMS Marketplace issuer network names, state-generated NetworkIds, and publisher-supplied provider-directory URL strings across PY2014-PY2026. This source does not contain provider membership, plan IDs, ServiceAreaIds, URL availability, or directory contents.","identity_key":"business_year,source_zip_sha256,source_row_number","row_count":null,"last_updated":"2026-07-15","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_network_puf_history has not been created or loaded.","notes":"The source bytes contain 10,514 certified logical rows across 13 annual ZIPs and three schema eras; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_network_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year","source_row_number","source_zip_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_business_rules_puf","source_fqn":"medicare_semantic.vw_business_rules_puf_current","title":"CMS CCIIO Business Rules PUF — Marketplace rating-rule history","domain":"commercial","stage":"semantic_view","status":"live","grain":"One logical publisher CSV record within one immutable (business_year, source_zip_sha256) artifact, keyed by one-based source_row_number.","description":"CMS Marketplace rules that modify how plan rates apply to enrollees and families, including dependent limits, relationship/cohabitation rules, tobacco-free periods, age determination, and medical/dental context. All official PY2014-PY2026 live artifacts are byte-certified; this is not a premium or provider-price source.","identity_key":"business_year,source_zip_sha256,source_row_number","row_count":null,"last_updated":"2026-07-15","raw_queryable_via":"Not queryable: proposed medicare_silver.fact_business_rules_puf_history has not been created or loaded.","notes":"The source bytes contain 77,304 certified logical rows across 13 annual ZIPs and four schema eras; row_count is null because no production table exists.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_business_rules_puf","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year","source_row_number","source_zip_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","superseded_by":null,"tools":["get_negotiated_rate","lookup_rates_for_npi","lookup_rates_for_tin","plan_commercial_price_proof","prove_commercial_price","replay_commercial_price_proof"],"dataset_id":"cms_transparency_in_coverage","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"retired","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":"RETIRED: not queryable through query_substrate (outside the queryable set). compute_median_rate / explain_rate return a deprecation steer, not data. Use the superseded_by path.","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":["RETIRED 2026-05-10 (two-payer-proof era, Fallon-only rows) and FROZEN: never rebuilt since. Any number computed from it is a Fallon-era artifact, not a market figure. Superseded by the canonical-graph resolution engine (see superseded_by).","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.","superseded_by":"The canonical-graph resolution engine over per-payer S3 primitives (curated_intermediate/payer=<p>/version=<v>/idx_rate_lookup/), served by get_negotiated_rate / lookup_rates_for_npi / prove_commercial_price; for raw SQL use vlada_curated.fact_rate (apply its ghost-rate + modifier caveats). See docs/architecture/2026-04-29-canonical-graph-resolution-engine.md.","tools":[],"dataset_id":"cms_transparency_in_coverage","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["code"],"backing_store":"glue"},{"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","raw_queryable_via":"Internal — reached via services/api/resolution_engine.py, not direct SQL.","notes":"No array<npi>; no LATERAL VIEW explode (flat-schema canonical-primitives lock).","superseded_by":null,"tools":["get_negotiated_rate","lookup_rates_for_npi","lookup_rates_for_tin"],"dataset_id":"ds_commercial_idx","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"index","purpose":"lookup","entity_keys":[],"entity_key_columns":{},"technical_keys":["rate_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena: vlada_curated.dim_payer","notes":null,"superseded_by":null,"tools":[],"dataset_id":"vlada_w1_payer_identity","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["payer_id"],"backing_store":"glue"},{"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","raw_queryable_via":"S3 prefix s3://vlada-platform-raw/commercial_v2/ (object store; not row-queryable).","notes":"364K files tracked across ~54 payers configured.","superseded_by":null,"tools":[],"dataset_id":"ds_commercial_tic","dataset_assignment_basis":"source_id_prefix","layer":"raw","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["source_file_id"],"backing_store":"s3"},{"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.","superseded_by":null,"tools":["plan_hospital_price","prove_hospital_price","replay_hospital_price","state_expert"],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"S3 prefix s3://vlada-platform-raw/hospital/ (object store; not row-queryable).","notes":"Parsed by pipelines/streaming_hospital_parser.py.","superseded_by":null,"tools":[],"dataset_id":"ds_hospital_hpt","dataset_assignment_basis":"source_id_prefix","layer":"raw","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"s3"},{"source_id":"medicare_pfs","source_fqn":"medicare_silver.fact_pfs_rvu","title":"Medicare Physician Fee Schedule (PFS)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, modifier, calendar_year) -- CMS PFS RVU components (work/PE/MP RVUs + conversion_factor). DEEP CY2003-2026. Filter conversion_factor BETWEEN 20 AND 50. RBP prices at the claim service year (as-of). The shallow medicare_physician_fee_schedule is the deprecated recent-years RDS mirror.","description":"The universal benchmark denominator for the commercial-to-Medicare ratio (\"is this rate fair?\"). National payment is DERIVED (fact_pfs_rvu stores components, not precomputed totals): office = total_non_facility_rvu*conversion_factor, facility = total_facility_rvu*conversion_factor. MATCH MODIFIER vs commercial (26 read / TC technical / global = NULL). No locality column; join medicare_gpci_locality / medicare_zip5_locality for a locality-adjusted rate.","identity_key":"hcpcs_code","row_count":642307,"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.fact_pfs_rvu -- 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.","Source-truth 2026-07-05 found 1,432 CY2022-CY2025 rows with implausible conversion_factor/payment values; the universal benchmark view quarantines them, but the underlying table is still unrepaired.","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.","CY2003-CY2021 official CMS RVU files are URL/SHA/dry-run pinned in docs/reference/source-audit/source-mastery/manifests/large-wave/medicare_pfs_resolved_cms_files.json; historical replay remains gated on repair, source lineage, effective-period/currentness, and CY2005 duplicate policy.","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":"CERTIFIED through the Source Acceptance Gate (product1-cert-pfs-v1). Proven: 99213 cigna 0.93x, premera 1.54x Medicare. The old medicare_silver.dim_medicare_pfs name was never built; no get_medicare_rate tool exists — write the SQL.","superseded_by":null,"tools":["medicare_allowed"],"dataset_id":"cms_pfs_relative_value_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_opps","source_fqn":"medicare_silver.fact_opps_addendum_b","title":"Medicare OPPS (hospital outpatient)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, calendar_year, effective_period) -- CMS OPPS Addendum B APC payment_rate + status_indicator. DEEP CY2004-2026; within-year corrections via effective_period_start + cms_vintage_sequence (no quarter column). RBP prices as-of the service quarter. The shallow medicare_opps_rates is the deprecated recent-years mirror.","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":1290799,"last_updated":"2026-06-03","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_opps_addendum_b -- JOIN vlada_curated.fact_hospital_chargemaster ON billing_code=hcpcs_code (outpatient).","notes":"CERTIFIED through the Source Acceptance Gate (product1-cert-opps-v1). 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.","superseded_by":null,"tools":["medicare_allowed"],"dataset_id":"cms_opps_addendum_b","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ipps_final_rule","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:msdrg"],"entity_key_columns":{"cms:msdrg":["ms_drg"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_asc","source_fqn":"medicare_silver.fact_asc_addendum","title":"Medicare ASC (Ambulatory Surgery Center) rates","domain":"medicare","stage":"silver","status":"live","grain":"One row per (hcpcs_code, calendar_year, effective_period) -- Medicare ASC Addendum payment_rate + payment_indicator. DEEP 2001-2026. The shallow medicare_asc_rates is the deprecated recent-years mirror.","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":462343,"last_updated":"2026-06-03","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_asc_addendum","notes":"CERTIFIED (product1-cert-asc-v1). Historical source manifest: docs/reference/source-audit/source-mastery/manifests/large-wave/medicare_asc_resolved_cms_files.json.","superseded_by":null,"tools":["medicare_allowed"],"dataset_id":"cms_asc_addenda","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_clfs","source_fqn":"medicare_silver.medicare_clfs_rates","title":"Medicare CLFS (Clinical Laboratory Fee Schedule)","domain":"medicare","stage":"silver","status":"retired","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","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.","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.","superseded_by":"medicare_silver.fact_clfs_national_rate (stamped re-collection 2026-09-07: every quarterly release 2019Q1-2026Q3 incl. modifier rows, with source_url, sha256_content_hash, asserted_at; the legacy table held one release, 2025 Q1, unmodified rows only, and stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_clfs","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_fact_clfs_national_rate","source_fqn":"medicare_silver.fact_clfs_national_rate","title":"CMS Clinical Laboratory Fee Schedule national limitation amounts, quarterly releases 2019-2026, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per calendar_year x quarter x HCPCS x modifier as published; natural key (calendar_year, quarter, row_seq); 55,116 rows over 29 releases (2019Q1-2026Q3) on 2026-09-07.","description":"Every quarterly CLFS release since 2019 re-collected through the provenance envelope on 2026-09-07: indicator and national_limit_amount as published, modifier rows kept (the legacy medicare_clfs_rates held a single release, 2025 Q1, unmodified rows only). The 2019 files come from CMS's old Downloads path; 2023Q4 and later sit behind the AMA CPT click-through license, accepted openly with the license page kept in bronze. CPT descriptors are not stored. release = the publisher slug (e.g. 26clabq3); 20clabq2 is a publisher gap (the release page names a file CMS no longer serves).","identity_key":"hcpcs_code","row_count":55116,"last_updated":"2026-09-07","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_clfs_national_rate","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.","superseded_by":null,"tools":["medicare_allowed"],"dataset_id":"cms_clfs_national_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_county_ratebook","notes":"CERTIFIED (product1-cert-ma-ratebook-v1). Current modern era remains served unchanged; legacy 1990-2014 bytes are secured in an exact deferred lane.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_county_ratebook","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["ssa_county_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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)","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.","superseded_by":null,"tools":["get_stars"],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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)","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.","superseded_by":null,"tools":["get_stars"],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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)","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).","superseded_by":null,"tools":["get_stars_cutpoints"],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["measure_id"],"backing_store":"glue"},{"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)","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).","superseded_by":null,"tools":[],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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)","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).","superseded_by":null,"tools":[],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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)","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.","superseded_by":null,"tools":["get_stars"],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["measure_id"],"backing_store":"glue"},{"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)","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).","superseded_by":null,"tools":[],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["rating_year"],"backing_store":"glue"},{"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)","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_star_ratings","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["from_measure_id"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_general","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_hedis_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_frm","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":["get_hos"],"dataset_id":"cms_ma_hos","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_mui","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":["get_hos"],"dataset_id":"cms_ma_hos","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_oto","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":["get_hos"],"dataset_id":"cms_ma_hos","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_hos_pao","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":["get_hos"],"dataset_id":"cms_ma_hos","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_measures","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_hedis_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_national_rates","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_hedis_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["measure_code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_rau_measures","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_hedis_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hedis_service_area","notes":"Grain-governed; live in Glue / query_substrate. Source family ma_hedis_annual.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_hedis_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","known_gaps":["Coverage: 2006-10 onward, monthly; the newest month is max(report_month), loaded as CMS posts it (by the 15th).","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family ma_contract_service_area.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","known_gaps":["Coverage: 2008-06 onward, monthly; the newest month is max(report_month), loaded as CMS posts it (by the 15th).","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.","superseded_by":null,"tools":["get_market_share"],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["fipsst"],"backing_store":"glue"},{"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,plan_id,segment_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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_plan_finder_mpf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["report_year"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["report_year"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_pbp_mrx","source_fqn":"medicare_silver.pbp_mrx","title":"MA pbp mrx","domain":"medicare","stage":"silver","status":"partial","grain":"One row per (contract_id, plan_id, segment_id, version, mrx_grp_type_id, mrx_grp_id, report_year, quarter). mrx_grp_type_id/mrx_grp_id are CMS-native 2006 legacy group identifiers; modern rows retain nulls where the source does not publish them.","description":"Part D Rx plan-level/group detail from mrx.txt. Coverage begins in 2006; insulin/IRA fields are added in later eras. Legacy repeated rows are retained at the source-native MRx group grain.","identity_key":"contract_id,plan_id,segment_id,version,mrx_grp_type_id,mrx_grp_id,report_year,quarter","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: 2006 → present (annual pre-2018 & 2025+; quarterly 2018-2024); 2001-2005 PBP ZIPs contain no MRx files.","Legacy key is source-native: mrx_grp_type_id + mrx_grp_id are required to retain repeated 2006 group rows; do not synthesize or collapse rows.","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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":["report_year","version"],"unmapped_key_tokens":["mrx_grp_id","mrx_grp_type_id","quarter"],"backing_store":"glue"},{"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":"One row per (contract_id, plan_id, segment_id, version, mrx_tier_id, report_year, quarter). mrx_tier_id is the CMS-native legacy row identifier; null benefit amounts remain null.","description":"Part D coverage-gap detail keyed by the source-native MRx tier identifier. Folded into pbp_mrx in 2026. Coverage: 2008-2025.","identity_key":"contract_id,plan_id,segment_id,version,mrx_tier_id,report_year,quarter","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: 2008-2025; the gapCoverage file first appears in the 2008 PBP ZIP and is folded into pbp_mrx in 2026.","The approved legacy key uses CMS-native mrx_tier_id; mrx_gap_id is not a reliable legacy identifier and must not be synthesized.","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":["report_year","version"],"unmapped_key_tokens":["mrx_tier_id","quarter"],"backing_store":"glue"},{"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":"One row per (contract_id, plan_id, segment_id, version, mrx_tier_post_id, mrx_tier_post_type_id, report_year, quarter). Keys are CMS-native post-tier identifiers. Coverage: 2007-present.","description":"Part D plan x pharmacy-tier formulary detail from mrx_p. The source-native post-tier identifiers retain repeated legacy rows without a synthetic mrx_p_id.","identity_key":"contract_id,plan_id,segment_id,version,mrx_tier_post_id,mrx_tier_post_type_id,report_year,quarter","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: 2007-present; mrx_p first appears in the 2007 PBP ZIP.","Use native mrx_tier_post_id + mrx_tier_post_type_id; do not collapse duplicate legacy groups or synthesize mrx_p_id.","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":["report_year","version"],"unmapped_key_tokens":["mrx_tier_post_id","mrx_tier_post_type_id","quarter"],"backing_store":"glue"},{"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":"One row per (contract_id, plan_id, segment_id, version, mrx_tier_id, mrx_tier_type_id, report_year, quarter). Plan x native tier identifier. Coverage: 2007-present.","description":"Part D Rx tier detail from mrx_tier.txt, keyed by both CMS-native tier identifiers so legacy repeated rows remain distinct.","identity_key":"contract_id,plan_id,segment_id,version,mrx_tier_id,mrx_tier_type_id,report_year,quarter","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: 2007-present; mrx_tier first appears in the 2007 PBP ZIP.","Native mrx_tier_id + mrx_tier_type_id are the certified legacy key; do not deduplicate by modern plan-level keys.","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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":["report_year","version"],"unmapped_key_tokens":["mrx_tier_id","mrx_tier_type_id","quarter"],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["table_name"],"backing_store":"glue"},{"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,plan_id,segment_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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","known_gaps":["Coverage: 2007-05 onward, monthly; the newest month is max(report_month), loaded as CMS posts it (by the 15th).","Uncertified; grain-governed."],"notes":"Grain-governed; live in Glue / query_substrate. Source family snp_data.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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_*.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:plan_id"],"entity_key_columns":{"cms:plan_id":["plan_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","provenance_chain_ref":"medicare_source_registry_cache","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.","SCOPE TRAP (learned 2026-07-26): this table is MA + Part D INCLUDING standalone PDP. Summing a county unfiltered overstates \"MA members\" (an agent reported LA County = 1.5M; true Dec-2025 MA enrolled = 963,559). For county-level MA use medicare_silver.ma_state_county_penetration (MA-scoped, carries eligibles + penetration + the FIPS<->SSA crosswalk) or filter CPSC to MA contract types. See docs/context_library/medicare/MA-CODEX.md (T2)."],"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).","superseded_by":null,"tools":["get_market_share","prove_ma_enrollment_trend"],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"live","grain":"One row per (contract_id, plan_id, month) plan-level enrollment count.","description":"CMS monthly MA and Part D enrollment at contract-plan-month grain. Direct guarded queries support plan-level population filters and as-reported parent rollups; SNP status comes from a separate membership source.","identity_key":"contract_id","row_count":null,"last_updated":"2026-05-13","freshness_sla":"Monthly (CMS enrollment release).","recollection":{"cadence":"monthly","watermark_field":"report_month","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.","report_month is the verified monthly DATE field. The metadata review date is not a new ingestion watermark."]},"raw_queryable_via":"Athena read-only via query_substrate: medicare_silver.enrollment_monthly_plan","provenance_chain_ref":"medicare_source_registry_cache","known_gaps":["Plan-level MA vocabulary includes separate HMO and HMOPOS labels; do not copy the contract-summary six-type filter. Use the source-bound taxonomy in vlada/semantic/ma_enrollment.py.","Raw plan enrollment is not certified by query success. December 2024 contracts H7245, H2765 and H9104 disagree with contract-summary totals in the original CMS files; stored suppression lower bounds also do not fully reconcile. Preserve source-specific values and disclose discrepancies.","December 2016-2025 periods and unique plan keys were verified on 2026-09-11. This is not a full-history or current-freshness certification; verify other requested periods and the annual SNP membership join."],"notes":"Live guarded query execution and ten-year parent rollups verified; 300 as-reported parent labels and 1486 parent-year records. Evidence: docs/product/2026-09-11-studio-ma-source-bound.ACTUAL.json. Live means queryable, not analytically certified.","superseded_by":null,"tools":["get_enrollment","prove_ma_enrollment_trend"],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Tools: plan_ma_enrollment_trend_proof / prove_ma_enrollment_trend; Athena: medicare_silver.plan_crosswalks_annual","notes":"Annual-snapshot sibling of the catalogued medicare_silver.dim_plan_crosswalk (source_id medicare_plan_crosswalk). status=partial; schema not asserted beyond grain.","superseded_by":null,"tools":["prove_ma_enrollment_trend"],"dataset_id":"cms_ma_plan_crosswalk","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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, by the 15th); the newest month is max(report_month).","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","provenance_chain_ref":"M-2 substrate (sha256_content_hash + source_url + asserted_at on every row).","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.","COLUMN TRAP (learned 2026-07-26): enrollment_count (TOTAL) = ma_only_count (members WITHOUT drug coverage, ~8% of MA) + part_d_count (MA-PD). ma_only_count is NOT \"MA as opposed to PDP\" \\u2014 an agent summed it as national MA and reported 2.86M vs the true ~35.4M. TOTAL MA = SUM(enrollment_count) WHERE plan_type IN ('HMO/HMOPOS','Local PPO','Regional PPO','PFFS','MSA','Medicare-Medicaid Plan HMO/HMOPOS').","THIS TABLE ALSO CONTAINS NON-MA ROWS: standalone PDP (~23.5M members), Employer-direct PDP, PACE, 1876 Cost, HCPP. Excluding them is a WHERE clause on plan_type, never a column swap. Dec-2025 rails: national MA ~35.4M; PDP ~23.5M. See docs/context_library/medicare/MA-CODEX.md (D1/T1/T5)."],"notes":"CERTIFIED (product1-cert-ma-enrollment-v1) on 237 months through 2026-04 (e.g. 2026-04 Humana 3.73M members); months loaded after that are served but were not part of that certification.","superseded_by":null,"tools":["get_enrollment","prove_ma_enrollment_trend"],"dataset_id":"cms_ma_monthly_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_ma_mlr","source_fqn":"medicare_silver.ma_mlr","title":"MA / Part-D Medical Loss Ratio (MLR)","domain":"medicare","stage":"silver","status":"retired","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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_mlr","notes":"New source captured end-to-end (PRs","superseded_by":"medicare_silver.fact_ma_mlr (stamped re-collection 2026-09-07: same rows plus the provenance envelope (source_url, sha256_content_hash, asserted_at); the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_ma","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_fact_ma_mlr","source_fqn":"medicare_silver.fact_ma_mlr","title":"CMS MA / Part D Medical Loss Ratio public-use files CY2014-CY2023, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per contract_year x contract; 4,984 rows over 10 contract years on 2026-09-07.","description":"The MLR public-use files re-collected through the provenance envelope on 2026-09-07 (identical row counts and spot values to the legacy ma_mlr). detail_available = 'true' marks the wide years (2014-2017, 2023) where every MLR report line is published; 2018-2022 carry only adjusted MLR and remittance. Strings; cast on read.","identity_key":"contract_id","row_count":4984,"last_updated":"2026-09-07","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ma_mlr","notes":"New source captured end-to-end (PRs","superseded_by":null,"tools":[],"dataset_id":"cms_ma_mlr","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","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,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","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,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"retired","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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.facility_cost_report_unit","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.","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,"superseded_by":"medicare_silver.fact_facility_cost_report_unit (stamped re-collection 2026-09-07: same rows and rules plus the provenance envelope (source_url, sha256_content_hash, asserted_at); the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_facility","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_fact_facility_cost_report_unit","source_fqn":"medicare_silver.fact_facility_cost_report_unit","title":"Facility cost reports — non-acute unit-cost metrics, stamped (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); partitioned by partition_key = <form>_<fy_year>. 1,046,007 rows on 2026-09-07 across 57 form-years.","description":"The non-acute ACTUAL-COST unit lens, re-collected through the provenance envelope on 2026-09-07 (same cells, validation and plausibility rules as the legacy facility_cost_report_unit; every row carries source_url, sha256_content_hash, asserted_at). Use computed_value as the direct unit cost. Do not convert these rows into fake CCRs.","identity_key":"ccn","row_count":1046007,"last_updated":"2026-09-07","recollection":{"cadence":"quarterly","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; CMS refreshes the all-years zips quarterly and HHA per fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_facility_cost_report_unit","provenance_chain_ref":"pipelines/medicare/ingest/hcris_non_hospital_runner.py (job build_medicare_hcris_non_hospital) from CMS HCRIS HHA20FY{year}.ZIP (per fiscal year) and HOSPC14 / RNL11 / FQHC14 / RHC17 -ALL-YEARS.zip; bronze medicare/bronze/cms_hcris_non_hospital_forms/; RDS registry medicare_source_registry_cache","known_gaps":["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 and must not drive pricing (2 ESRD rows flagged on 2026-09-07).","All value columns are strings as published: cast numerics on read; filter validation_ok='true' and plausible='true'.","Joining requires a real facility CCN; never guess it onto an NPI."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_non_hospital_forms","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"retired","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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.facility_cost_report_ccr","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.","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,"superseded_by":"medicare_silver.fact_facility_cost_report_ccr (stamped re-collection 2026-09-07: same rows and rules plus the provenance envelope (source_url, sha256_content_hash, asserted_at); the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_facility","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medicare_fact_facility_cost_report_ccr","source_fqn":"medicare_silver.fact_facility_cost_report_ccr","title":"Facility cost reports — HHA supplies/drugs/devices cost-to-charge rows, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per (ccn, fiscal-year-end, HHA Worksheet C Part II line); partitioned by partition_key = hha_<fy_year>. 29,692 rows on 2026-09-07.","description":"HHA Worksheet C Part II cost-to-charge rows (medical supplies, vaccines/drugs, administration, covered disposable devices), re-collected through the provenance envelope on 2026-09-07 with the same validation and charge_as_cost rules as the legacy facility_cost_report_ccr. Not a whole-agency ratio.","identity_key":"ccn","row_count":29692,"last_updated":"2026-09-07","recollection":{"cadence":"quarterly","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; HHA files are per fiscal year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_facility_cost_report_ccr","provenance_chain_ref":"pipelines/medicare/ingest/hcris_non_hospital_runner.py (job build_medicare_hcris_non_hospital) from CMS HCRIS HHA20FY{year}.ZIP; bronze medicare/bronze/cms_hcris_non_hospital_forms/","known_gaps":["HHA only; the other four forms publish no cost-to-charge lines.","Exclude charge_as_cost='true' rows (charges reported as costs) and rows with validation_ok='false' or plausible='false'.","All value columns are strings as published: cast on read."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_non_hospital_forms","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_puf_outpatient_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_part_c","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_plan_payment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_part_d","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_plan_payment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_plan_payment_county","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_plan_payment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["ssa_county_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_hcc_coefficients","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_risk_adjustment_model","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["rate_year"],"backing_store":"glue"},{"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 (rate_year, model_version, icd_code, hcc_category); an ICD-10 code may map to multiple HCCs.","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":"rate_year,model_version,icd_code,hcc_category","row_count":171676,"last_updated":"2026-06-08","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_icd10_hcc_crosswalk","known_gaps":["REFERENCE crosswalk (not contract-keyed): the certified row grain is (rate_year, model_version, icd_code, hcc_category); do not collapse multiple HCC mappings.","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_risk_adjustment_model","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["hcc_category","icd_code","model_version","rate_year"],"backing_store":"glue"},{"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":"retired","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,plan_id,segment_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","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,"superseded_by":"medicare_silver.fact_ma_landscape (stamped re-collection 2026-09-07: same rows plus the provenance envelope (source_url, sha256_content_hash, asserted_at); the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_landscape","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_fact_ma_landscape","source_fqn":"medicare_silver.fact_ma_landscape","title":"CMS MA / Part D Landscape, every era CY2006-CY2026, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per report_year x record_family x category x plan (contract, plan, segment) as published; natural key (report_year, row_seq); 1,684,158 landscape rows + plan-and-premium rows; 78 year x category partitions on 2026-09-07.","description":"The CMS Landscape files re-collected through the provenance envelope on 2026-09-07: 38 header signatures across three publisher eras (2006 premium-only; 2007-2024 per-category files; CY2025+ one combined file) resolved by exact header contracts (pipelines/medicare/silver/ma_landscape_contracts.yaml); every row carries source_url, sha256_content_hash, asserted_at. Filter record_family = 'landscape' AND is_current for the plan roster; record_family = 'plan_premium' holds the plan-and-premium files. Column mapping stress-tested (docs/knowledge/recollection/landscape-stress-test-2026-09-06.md); the 2010 MA 'MOOP $3,400' column is the Yes/No flag moop_at_or_below_3400_flag, not an amount.","identity_key":"contract_id,plan_id,segment_id","row_count":1684158,"last_updated":"2026-09-07","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":["The next contract year's file drops in late September; in-year revisions (e.g. 2026 202608) replace the year's partition.","watermark_field 'report_year' is the contract year the file describes; the next year's file drops in late September and an in-year revision replaces that report_year partition."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ma_landscape","commercial_terms":"Public CMS data.","provenance_chain_ref":"pipelines/medicare/ingest/ma_landscape_runner.py (job build_medicare_ma_landscape) from https://www.cms.gov/files/zip/cy2006-cy2025-landscape-files.zip (sha 3f034779fe00...) and cy2026-landscape-202608.zip (sha a7c016028815...); member ledger medicare_silver.ma_landscape_member_ledger; bronze medicare/bronze/cms_ma_landscape/","context_doc_path":"docs/context_library/medicare/ma_enrollment_cpsc.md","known_gaps":["Strings as published ('$-', 'Not Applicable', '($12.60)', 'x' are legitimate publisher tokens); cast on read.","The 2026 file carries the July 2026 star update; stars_ratings_summary holds the October 2025 release (47 contracts differ).","plan_crosswalks_annual has no plan_year 2025 rows, so 2025 departures cannot be classified against the crosswalk."],"notes":null,"superseded_by":null,"tools":["get_landscape","get_pbp_benefit"],"dataset_id":"cms_ma_landscape","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_nadac","source_fqn":"drug_silver.fact_drug_acquisition_cost","title":"NADAC — National Average Drug Acquisition Cost","domain":"drug","stage":"silver","status":"live","grain":"One row per (ndc11, observed_period_start/week, price_type). CERTIFIED 2026-06-03; history gap CLOSED and re-measured 2026-08-10 (see known_gaps).","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":16260115,"last_updated":"2026-08-10","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_acquisition_cost (is_current = true)","notes":"CERTIFIED (product1-cert-nadac-v1). Full 2013-2026 history served; the former current-window scoping is retired. Acquisition cost != payment/list/net.","superseded_by":null,"tools":[],"dataset_id":"cms_nadac","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Tool: asp_pricing_lookup; Athena: drug_silver.fact_drug_asp_quarterly (filter is_current = true).","notes":"Logical catalog alias over physical table drug_silver.fact_drug_asp_quarterly; HCPCS<->NDC crosswalk is a separate quarterly drop.","superseded_by":null,"tools":["asp_pricing_lookup"],"dataset_id":"ds_drug_asp","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","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.","superseded_by":null,"tools":["asp_pricing_lookup"],"dataset_id":"cms_asp_pricing_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_asp_ndc_hcpcs_crosswalk","source_fqn":"drug_silver.fact_asp_ndc_hcpcs_crosswalk","title":"ASP NDC-HCPCS Crosswalk — Medicare Part B drug-identity bridge (raw CMS drop)","domain":"drug","stage":"silver","status":"live","grain":"One row per (hcpcs_code, ndc11).","description":"The CMS Medicare Part B ASP NDC-HCPCS Crosswalk: each Part-B HCPCS (J-code etc.) mapped to the NDCs billable under it, with labeler/drug name, HCPCS dosage, package size/qty, and billing units. This is the drug-IDENTITY bridge previously flagged missing — it lets a J-code resolve to its NDC set (drug_silver.dim_drug.ndc11) and an NDC resolve back to its HCPCS (vlada_curated.dim_code.code), unifying the drug catalog with the medical/HCPCS graph. Sibling of the ASP Pricing File (fact_drug_asp_quarterly) in the same quarterly ASP release.","identity_key":"hcpcs_code","row_count":7366,"last_updated":null,"freshness_sla":"Quarterly (CMS ASP release, NDC-HCPCS Crosswalk ZIP).","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.","is_current flag marks the live vintage; ~6-month publication lag."]},"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_asp_ndc_hcpcs_crosswalk (filter is_current = true). hcpcs_code JOINs vlada_curated.dim_code.code (measured 850/850 = 100%); ndc11 JOINs drug_silver.dim_drug.ndc11 (measured 7,140/7,189 = 99.3%). NDC stored canonical 11-digit (segment-aware); ndc_raw preserves the source dashed form.","known_gaps":["July 2026 quarter loaded (7,366 rows, 850 HCPCS, 7,189 NDC11) verified 2026-07-14 by Athena. Runner is idempotent by ZIP SHA + replace-mode per quarter partition.","Only the ASP crosswalk member is loaded; the AWP / OPPS / PrEP NDC-HCPCS Crosswalk siblings in the same ZIP are deferred (separate billing settings).","Historical quarters (2021Q1+) are discoverable from the same CMS page but not yet backfilled — current snapshot only.","billunits / billunitspkg are per-package HCPCS billing-unit conversions — unit-normalize before any per-NDC dose or price math."],"notes":"The drug-identity NDC<->HCPCS bridge (2026-07-14). Unified the previously-disjoint drug + medical graph components — see docs/architecture/2026-07-14-source-connection-node-graph.md. One J-code -> many NDCs.","superseded_by":null,"tools":[],"dataset_id":"cms_asp_pricing_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_form5500_insurance","source_fqn":"drug_silver.fact_form5500_insurance","title":"Form 5500 Schedule A insurance contracts (carrier, premiums, broker totals)","domain":"drug","stage":"silver","status":"live","grain":"One row per (filing, Schedule A attachment) - key (ack_id, plan_year, form_id); served plan years 2009-2025. Plan year 2025 is PARTIAL.","description":"DOL EFAST2 Form 5500 Schedule A insurance-contract rows: carrier identity and NAIC, premiums, persons covered, aggregate broker commission and fee totals, and welfare-benefit-type indicators (health/dental/vision/stop-loss/HMO/PPO/indemnity). Presence of a Schedule A row is evidence the plan is at least partially insured; is_stop_loss disambiguates insured from self-funded-with-stop-loss. First loaded 2026-07-26.","identity_key":"ack_id","row_count":5112373,"last_updated":"2026-07-26","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 Form 5500 plan year of the filing, the DOL EFAST2 edition axis (one Latest archive per plan year); it is not the date DOL released the archive.","The newest plan year is always partial because DOL refreshes a plan year's Latest archive as late filings arrive: PY2025 holds 53,926 rows against a 288,195-339,145 norm, so never trend it; the last complete plan year is 2024.","Amended filings coexist in the table; read is_current = true.","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: drug_silver.fact_form5500_insurance (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_a.md","known_gaps":["OUTLIER CONTAMINATION: naive sum(broker_comm_tot_usd) is $576 trillion - as-filed filer error, not a real total. Never aggregate without an explicit outlier policy; prefer row-level reporting traced to ack_id.","986,069 of 5,112,373 rows are health contracts; the rest are dental, vision, life, disability and pension. Filter is_health before any health-plan claim.","Plan year 2025 is PARTIAL (53,926 rows vs a 288,195-339,145 norm); never trend it. Last complete plan year is 2024.","Broker commissions here cover INSURED products only. Self-funded vendor fees live on Schedule C (fact_form5500_service_provider); a complete broker-fee answer needs both."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_form5500_insurance_broker","source_fqn":"drug_silver.fact_form5500_insurance_broker","title":"Form 5500 Schedule A named brokers (per-broker commission and fees paid)","domain":"drug","stage":"silver","status":"live","grain":"One row per (filing, Schedule A attachment, named broker) - key (ack_id, plan_year, form_id, row_order); served plan years 2009-2025. Plan year 2025 is PARTIAL.","description":"DOL EFAST2 Form 5500 Schedule A PART1 rows: the named broker on each insurance contract with the commission and fees actually paid to them. 6,733,606 rows across 17 plan years - the per-broker compensation record for insured arrangements. First loaded 2026-07-26.","identity_key":"ack_id","row_count":6733606,"last_updated":"2026-07-26","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 Form 5500 plan year of the filing the broker row is attached to, the DOL EFAST2 edition axis (one Latest archive per plan year); it is not the date DOL released the archive.","The newest plan year is always partial because DOL refreshes a plan year's Latest archive as late filings arrive: PY2025 holds 80,515 rows against a 372,280-449,092 norm, so never trend it.","Amended filings coexist in the table; read is_current = true.","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: drug_silver.fact_form5500_insurance_broker (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_a.md","known_gaps":["EXTREME OUTLIER CONCENTRATION: a SINGLE row carries $563,333,333,333,333 of the $573,158,066,326,117 naive sum(broker_comm_paid_usd) - 98.2% in one filer-entered value. Five rows exceed $1B; median is $2,119. Never sum naively.","397,021 distinct broker_name strings are RAW filer text with no entity canonicalization; the same broker appears under many spellings. Distinct names are not distinct firms.","Plan year 2025 is PARTIAL (80,515 rows vs a 372,280-449,092 norm); never trend it.","INSURED contracts only; self-funded vendor fees live on Schedule C."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_form5500_financials","source_fqn":"drug_silver.fact_form5500_financials","title":"Form 5500 Schedule H plan financials (claims paid, admin expenses, assets)","domain":"drug","stage":"silver","status":"live","grain":"One row per filing that attached a Schedule H - key ack_id ALONE (Schedule H has no FORM_ID column); served plan years 2009-2025. Plan year 2025 is PARTIAL.","description":"DOL EFAST2 Form 5500 Schedule H rows: benefits actually paid (tot_distrib_bnft_usd), carrier-paid benefits, the itemized administrative-expense block including contract-administrator/TPA fees, contributions, income and beginning/end-of-year assets. This is the CLAIMS-PAID denominator: Schedule C says what the plan paid its vendors, Schedule A says what it paid its carrier and broker, and only Schedule H says what it paid for CARE. All 1,513,019 rows join to fact_form5500_filing on ack_id. First loaded 2026-07-26.","identity_key":"ack_id","row_count":1513019,"last_updated":"2026-07-26","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 Form 5500 plan year of the filing (the DOL EFAST2 edition axis and the table's partition); Schedule H has no FORM_ID, so ack_id alone is the key within a plan year.","The newest plan year is always partial because DOL refreshes a plan year's Latest archive as late filings arrive: PY2025 holds 2,548 rows against an 86,077-100,501 norm, so never trend it; the last complete plan year is 2024.","Amended filings coexist in the table; read is_current = true.","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: drug_silver.fact_form5500_financials (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_h.md","known_gaps":["PENSION CONTAMINATION: only 64,574 of 1,513,019 rows (4.3%) belong to a plan flagged is_health_plan; 1,281,230 carry a pension benefit code. Unfiltered sum(tot_distrib_bnft_usd) is $13.56T of which only $2.39T (17.6%) is health. The largest rows are GM PY2012 $27.6B, IBM PY2022 $19.7B, AT&T PY2023 $12.5B - all pension. ALWAYS join fact_form5500_filing and filter is_health_plan.","LARGE-PLAN-ONLY: Schedule H is filed by 100+ participant plans; small plans file Schedule I, which is NOT ingested. PY2024 has 86,077 Schedule H rows against 221,777 filings. Absence of a row is not evidence of zero claims.","The usable HEALTH universe is ~3,300-5,000 plan-years per year (64,574 across the era, 7,108 distinct sponsor EINs), not ~86,000. Most large health plans are unfunded or insured and file no Schedule H.","Fee-to-claims exposure ratio is computable for 56,959 of 64,574 health plan-years (88.2%) - those carrying both a Schedule H and a Schedule C row on the same ack_id.","FOUR SCHEMA ERAS (143/153/158/166 columns at 2009/2015/2022/2023). Projection is name-based and every field was verified in all four eras. Seven 2023+ fee fields are deliberately not projected because a null across two thirds of the range reads as 'no fee'.","contract_admin_fees_usd is populated on only 49.7% of rows and is an INDEPENDENT filing from Schedule C; the two need not agree.","AS-FILED: 228 rows are negative (min -$142,949,953) and 119,590 are exactly zero. tot_expenses_usd INCLUDES benefits paid and is not a fee figure.","Plan year 2025 is PARTIAL (2,548 rows vs an 86,077-100,501 norm); never trend it. Last complete plan year is 2024."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":4330525,"last_updated":"2026-07-26","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 at 4,330,525 filing rows; the SIX-table EFAST2 family totals 32,402,086 rows (filing, Schedule C providers + codes, Schedule A insurance + brokers, Schedule H financials). The prior 'three-table family / 13,037,746 rows' figure predates the 2026-07-26 Schedule A and Schedule H loads.","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.","superseded_by":null,"tools":["pbm_compensation_rollup"],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":4147907,"last_updated":"2026-07-26","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 at 4,147,907 service-provider rows; the SIX-table EFAST2 family totals 32,402,086 rows. Schedule C covers SELF-FUNDED vendor compensation only; broker commissions on insured products live on fact_form5500_insurance_broker and claims paid live on fact_form5500_financials.","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.","superseded_by":null,"tools":["pbm_compensation_rollup"],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena: drug_silver.fact_drug_consumer_price (filter source; employer_cpd_carve_out uses source = 'costplusdrugs')","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.","superseded_by":null,"tools":[],"dataset_id":"cost_plus_drugs_consumer_prices","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Tool: wac_pricing_lookup; Athena: drug_silver.fact_drug_hcai_sb17_wac_increase","notes":"2024-04-01 regulatory change swapped unit-sales for gross-sales-USD.","superseded_by":null,"tools":[],"dataset_id":"ca_hcai_sb17_wac_increases","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Tool: ira_mfp_exposure; Athena: drug_silver.fact_drug_reimbursement (filter price_type='ira_mfp' and is_current=true)","notes":"Implemented end-to-end (pipelines/drug/silver/ira_mfp_*); parser serves only valid MFP price intervals and profiles raw CMS update rows separately.","superseded_by":null,"tools":["ira_drug_label_risk_screen","ira_mfp_exposure"],"dataset_id":"ds_drug_ira","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Empty scaffold — use drug_spuf_formulary (drug_silver.fact_drug_formulary) for live formulary data.","notes":"Retained for traceability; see docs/architecture/2026-05-17-spuf-formulary-substrate-assignment.md.","superseded_by":null,"tools":[],"dataset_id":"ds_drug_formularies","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":["formulary_churn"],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["drug_identifier"],"backing_store":"glue"},{"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,plan_id,segment_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)","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.","superseded_by":null,"tools":["formulary_churn"],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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)","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.","superseded_by":null,"tools":[],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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)","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.","superseded_by":null,"tools":[],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"contract_id,plan_id,segment_id,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)","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.","superseded_by":null,"tools":[],"dataset_id":"cms_part_d_spuf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id","fda:ndc"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"],"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"drug_orange_book","source_fqn":"drug_silver.dim_orange_book_product","title":"FDA Orange Book (patents + exclusivity)","domain":"drug","stage":"silver","status":"partial","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":["Tilde-delimited; patent/exclusivity date formats vary across vintages."],"notes":"Companion facts fact_orange_book_patent + fact_orange_book_exclusivity.","superseded_by":null,"tools":[],"dataset_id":"fda_orange_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["application_number"],"backing_store":"glue"},{"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,"raw_queryable_via":null,"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).","superseded_by":null,"tools":[],"dataset_id":"ds_drug_purple","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"reference","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["bla_number"],"backing_store":"glue"},{"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,"raw_queryable_via":"Tool: biosimilar_window; Athena: drug_silver.dim_purple_book_product","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).","superseded_by":null,"tools":[],"dataset_id":"fda_purple_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["bla_number"],"backing_store":"glue"},{"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,"raw_queryable_via":"Tool: dea_schedule_lookup (catalog metadata + scouted parser)","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.","superseded_by":null,"tools":[],"dataset_id":"ds_drug_dea","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"reference","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["dea_number"],"backing_store":"glue"},{"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,"raw_queryable_via":"Tool: dea_schedule_lookup; Athena: drug_silver.dim_dea_ndc_schedule","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.","superseded_by":null,"tools":[],"dataset_id":"dea_controlled_substance_schedules","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Tool: open_payments_prescriber_corr; Athena: drug_silver.fact_drug_payment_to_prescriber","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. 2026-08-03 added the device-slice parser/writer under a separate acceptance gate; the drug ingest path is unchanged and device parsing is off unless --with-device is passed.","superseded_by":null,"tools":["excluded_prescriber_payment_screen"],"dataset_id":"cms_open_payments","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["payment_id"],"backing_store":"glue"},{"source_id":"cms_nppes_data_dissemination","source_fqn":"s3://vlada-platform-raw/nppes","title":"CMS NPPES Data Dissemination release bundle","domain":"provider_identity","stage":"raw","status":"design_locked","grain":"Publication bundle with separate grains: NPI main row; NPI x practice location; NPI x alias; NPI x endpoint; monthly deactivation NPI.","description":"Immutable upstream CMS NPPES V2 full-replacement bundle plus the separate monthly deactivation report. Shadow observations preserve all locations, taxonomies, other identifiers, aliases, endpoints, status, and row-level lineage; no NPI=care-site assertion.","identity_key":"observation_id (release + member + source row + observation family + family subkey + canonical row hash)","row_count":56874736,"last_updated":"2026-07-21","raw_queryable_via":"S3 immutable observations under the certified July release prefix; no accepted serving pointer.","notes":"Public EIN and parent-organization TIN are suppressed; never infer. NPI issuance does not validate licensure or credentialing.","superseded_by":null,"tools":[],"dataset_id":"ds_cms_nppes","dataset_assignment_basis":"source_id_prefix","layer":"raw","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["canonical","family","hash","member","observation","observation_id","release","row","source","subkey"],"backing_store":"s3"},{"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. From nppes_version 2026-09, taxonomy is the PRIMARY taxonomy (Primary Taxonomy Switch = Y); taxonomy_code_1 keeps Taxonomy Code_1 as printed (the pre-2026-09 meaning).","identity_key":"npi","row_count":9798758,"last_updated":"2026-09-23","raw_queryable_via":"Tool: provider_substrate_lookup; Athena: vlada_curated.dim_provider","provenance_chain_ref":null,"notes":"entity_type 1 = individual, 2 = organization. taxonomy semantics are versioned: through 2026-03 Taxonomy Code_1 as printed; from 2026-09 the primary taxonomy (differs from Code_1 for 976,458 of 9,798,758 NPIs in the September 2026 release); taxonomy_basis names the rule; nppes_source_sha256 is the release zip.","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"cms_nppes_data_dissemination","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"vlada_w2_medicare_benchmarks","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:hcpcs","nppes:npi"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"],"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":["place_of_service"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena: vlada_curated.dim_clia_lab (Iceberg: medicare_silver.dim_clia_lab)","provenance_chain_ref":null,"notes":"Iceberg table medicare_silver.dim_clia_lab, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_pos_clia_laboratory_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["clia_number"],"backing_store":"glue"},{"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)","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."],"notes":"Iceberg table medicare_silver.dim_asc, partitioned by state_cd; one atomic per-state replace per quarterly ingest (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena: vlada_curated.dim_dialysis_facility (VIEW serving max(observed_period)); historian base table: medicare_silver.dim_dialysis_facility","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.","superseded_by":null,"tools":[],"dataset_id":"cms_medicare_dialysis_facilities","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":["observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Builder pipelines/spark/marts/build_mart_unified_pricing_b1.py (B1 slice); gold table not yet promoted.","notes":"Governed by docs/architecture/2026-04-25-hospital-commercial-unification.md.","superseded_by":null,"tools":[],"dataset_id":"ds_mart_unified","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Postgres vlada_enterprise: dim_substrate_mrf_version","notes":"dim_commercial_mrf_version is a back-compat view over this table.","superseded_by":null,"tools":[],"dataset_id":"ds_provenance_substrate","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"registry","purpose":"provenance","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["content_sha256"],"backing_store":"postgres"},{"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","raw_queryable_via":"Postgres vlada_enterprise: medicare_source_registry_cache","known_gaps":[],"notes":"Tracks cms_vintage_sequence + parse_revision + restatement chain.","superseded_by":null,"tools":[],"dataset_id":"ds_provenance_medicare","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"registry","purpose":"provenance","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":[],"backing_store":"postgres"},{"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","raw_queryable_via":"Postgres vlada_enterprise: drug_source_registry_cache","known_gaps":[],"notes":"Same column shape as migration 031, drug-specific natural-key naming.","superseded_by":null,"tools":[],"dataset_id":"ds_provenance_drug","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"registry","purpose":"provenance","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":[],"backing_store":"postgres"},{"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","raw_queryable_via":"Postgres vlada_enterprise: dim_mrf_version","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_provenance_hospital","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"registry","purpose":"provenance","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"postgres"},{"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,plan_id,segment_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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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.","superseded_by":null,"tools":["get_pbp_benefit"],"dataset_id":"cms_ma_pbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_pecos_public_provider_enrollment","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["enrollment_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_facility_affiliation","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.","superseded_by":null,"tools":[],"dataset_id":"cms_doctors_clinicians_facility_affiliation","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_nucc_taxonomy","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.","superseded_by":null,"tools":[],"dataset_id":"nucc_provider_taxonomy_code_set","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_icd10cm","notes":"Iceberg table drug_silver.dim_icd10cm. Runner: pipelines/drug/ingest/icd10cm_runner.py.","superseded_by":null,"tools":[],"dataset_id":"cms_icd10_cm_code_set","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["icd10cm_code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_icd10pcs","notes":"Iceberg table drug_silver.dim_icd10pcs. Runner: pipelines/drug/ingest/icd10pcs_runner.py.","superseded_by":null,"tools":[],"dataset_id":"cms_icd10_pcs_code_set","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["icd10pcs_code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug","notes":"Iceberg table drug_silver.dim_drug. Runner: pipelines/drug/ingest/fda_ndc_directory_runner.py.","superseded_by":null,"tools":["ira_mfp_exposure","recall_spend_window"],"dataset_id":"fda_ndc_directory","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_spending_part_d","notes":"Iceberg table drug_silver.fact_drug_spending_part_d. Runner: pipelines/drug/ingest/part_d_spending_runner.py.","superseded_by":null,"tools":["ira_mfp_exposure","recall_spend_window"],"dataset_id":"cms_part_d_spending_by_drug","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ipps_wage_index","source_fqn":"medicare_silver.fact_ipps_wage_index","title":"Medicare IPPS Wage Index (geographic wage adjustment)","domain":"medicare","stage":"reference","status":"live","grain":"One row per (fiscal_year, hospital CCN) -- IPPS wage index (with cap) for inpatient localization. DEEP FY2006-2026.","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":84746,"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":"Athena (read-only via query_substrate): medicare_silver.fact_ipps_wage_index (per fiscal_year, ccn). Also Python: vlada.rbp.wageindex.wage_index_for(ccn).","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":"Loaded by vlada/rbp/wageindex.py from vlada/rbp/ref/ipps_wage_index_2026.csv; source-truth dry-runs prove FY2006 and FY2008-FY2026 official CMS Table 2 artifacts, and build-ipps-wage-index writes the additive fact_ipps_wage_index_source_truth table with explicit asserted_at. Runner same-SHA skips verify intended rows before skipping. Serving remains Python-bundle scoped until accepted.","superseded_by":null,"tools":[],"dataset_id":"cms_ipps_final_rule","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"reference","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_dme_devices_supplies","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":["get_hospital_quality"],"dataset_id":"cms_care_compare_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":["get_hospital_quality"],"dataset_id":"cms_care_compare_hospitals","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_physician_other_practitioners","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_puf_inpatient_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["drg_cd"],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"cms_puf_outpatient_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["apc_cd"],"backing_store":"glue"},{"source_id":"medicare_ipps_base_rate","source_fqn":"medicare_silver.fact_ipps_base_rate","title":"Medicare IPPS Base Rate (operating + capital standardized amounts)","domain":"medicare","stage":"dim","status":"live","grain":"One row per (fiscal_year, capital_area, rate_context vintage) -- national IPPS standardized base = operating_std_amount + capital_std_amount. DEEP FY2006-2026; select capital_area=national, final_rule (a correction supersedes only when no final rule loaded), as-of fiscal year. The shallow dim_ipps_base_rate is deprecated.","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":66,"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.fact_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":"Completes absolute IPPS pricing with dim_msdrg (weights) + the wage index.","superseded_by":null,"tools":[],"dataset_id":"cms_ipps_final_rule","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["fiscal_year"],"backing_store":"glue"},{"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":"retired","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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_gpci_locality","notes":null,"superseded_by":"medicare_silver.fact_pfs_gpci_locality (stamped re-collection 2026-09-07: every RVU release CY2017-2026 GPCI file at source grain with source_url, sha256_content_hash, asserted_at; the legacy table was a single CY2025 RDS mirror snapshot of 109 rows; the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_gpci","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["locality_number"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_pfs_relative_value_files","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":["effective_date"],"unmapped_key_tokens":["calendar_year","payment_track"],"backing_store":"glue"},{"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,"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).","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).","superseded_by":null,"tools":[],"dataset_id":"cms_anesthesia_base_units","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":["calendar_year"],"backing_store":"glue"},{"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":"retired","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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_county_to_locality","notes":null,"superseded_by":"medicare_silver.fact_pfs_locality_config (stamped re-collection 2026-09-07: every RVU release CY2003-2026 LOCCO file at source grain with source_url, sha256_content_hash, asserted_at; the legacy table was a single CY2025 RDS mirror snapshot of 100 rows; the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_county","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["state_locality_counties_year"],"backing_store":"glue"},{"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":["watermark_field 'calendar_year' is the CMS payment-locality year a ZIP row maps for (the grain's year key); the quarterly ZIP-locality updates within a year are not distinguished by it."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_zip_to_locality","provenance_chain_ref":"medicare_silver M-2 substrate.","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,"superseded_by":null,"tools":[],"dataset_id":"cms_pfs_zip_carrier_locality","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["usps:zip"],"entity_key_columns":{"usps:zip":["zip_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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.","watermark_field 'year_quarter' is the CMS year-quarter label carried on each ZIP5 file row (parsed from the fixed-width file); because the table holds one loaded ZIP5 file per year it identifies which quarterly file was loaded, not a full quarterly history."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medicare_zip5_locality","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.","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.","superseded_by":null,"tools":[],"dataset_id":"cms_pfs_zip_carrier_locality","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["usps:zip"],"entity_key_columns":{"usps:zip":["zip_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["code"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["billing_code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_oig_leie","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.","superseded_by":null,"tools":["excluded_prescriber_payment_screen"],"dataset_id":"oig_leie_exclusions","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["row_uid"],"backing_store":"glue"},{"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 Corporate Integrity Agreement (by entity).","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","row_count":null,"last_updated":null,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_hhs_oig_cia","notes":null,"superseded_by":null,"tools":[],"dataset_id":"oig_corporate_integrity_agreements","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["entity_slug"],"backing_store":"glue"},{"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","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,"superseded_by":null,"tools":[],"dataset_id":"hrsa_340b_opais","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["id_340b"],"backing_store":"glue"},{"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","known_gaps":["An entity can map to multiple NPIs; not every covered entity publishes an NPI."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"hrsa_340b_opais","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["npi_number"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_part_d_prescriber","notes":null,"superseded_by":null,"tools":["excluded_prescriber_payment_screen"],"dataset_id":"cms_part_d_prescriber_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["prescriber_npi"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_spending_part_b","notes":null,"superseded_by":null,"tools":["ira_mfp_exposure"],"dataset_id":"cms_part_b_drug_spending","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_va_fss_price","notes":null,"superseded_by":null,"tools":[],"dataset_id":"va_fss_pharmaceutical_prices","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_medicaid_rebate_product","notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicaid_drug_rebate_program_product_file","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_medicaid_utilization","notes":null,"superseded_by":null,"tools":["ira_mfp_exposure","recall_spend_window"],"dataset_id":"cms_state_drug_utilization_data","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["ndc11"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_shortage","notes":null,"superseded_by":null,"tools":[],"dataset_id":"fda_drug_shortages","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["package_ndc"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_recall","notes":null,"superseded_by":null,"tools":["recall_spend_window"],"dataset_id":"fda_enforcement_reports_drug_recalls","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["recall_number"],"backing_store":"glue"},{"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":3673,"last_updated":"2026-09-23","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_fda_warning_letter","notes":null,"superseded_by":null,"tools":[],"dataset_id":"fda_warning_letters","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["letter_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_rxclass_class","known_gaps":["class_id is unique within a class_type; always carry class_type."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"nlm_rxclass","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["class_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_rxclass_membership","known_gaps":["RxCUI→NDC requires an RxNorm NDC crosswalk; membership is RxCUI-keyed."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"nlm_rxclass","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["nlm:rxcui"],"entity_key_columns":{"nlm:rxcui":["rxcui"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":["Dates are text fields (patent_expire_date_text) — parse defensively."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"fda_orange_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["patent_no"],"backing_store":"glue"},{"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":["Exclusivity dates are text (exclusivity_date_text); parse defensively."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"fda_orange_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["exclusivity_code"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug_label","notes":null,"superseded_by":null,"tools":["ira_drug_label_risk_screen"],"dataset_id":"fda_spl_drug_labels","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["fda:ndc"],"entity_key_columns":{"fda:ndc":["product_ndc"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_drug_application","notes":null,"superseded_by":null,"tools":["ira_drug_label_risk_screen"],"dataset_id":"fda_drugs_at_fda_applications","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["application_number"],"backing_store":"glue"},{"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.","superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["code"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_geography_hierarchy","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["usps:zip"],"entity_key_columns":{"usps:zip":["zip_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":["state_expert"],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["care_site_id"],"backing_store":"glue"},{"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","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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w2_medicare_benchmarks","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["system_name"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["system_id"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["billing_code"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.dim_state_metric","provenance_chain_ref":null,"notes":null,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_state_context_metrics","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["clinician_npi"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_transparency_in_coverage","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":[],"entity_key_columns":{},"technical_keys":["rate_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_transparency_in_coverage","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":[],"entity_key_columns":{},"technical_keys":["rate_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":["compare_hospital_rates","coverage_status"],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":["coverage_status"],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["rate_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["rate_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"cms_hospital_price_transparency","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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,"superseded_by":null,"tools":["medicare_allowed"],"dataset_id":"vlada_w2_medicare_benchmarks","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["billing_code"],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_spine_geography_hierarchy","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["hospital_ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"superseded_by":null,"tools":[],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["census:county_fips"],"entity_key_columns":{"census:county_fips":["county_fips"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_care_site_payer_coverage","provenance_chain_ref":null,"known_gaps":["Coverage reflects extracted payers; absence != no contract."],"notes":null,"superseded_by":null,"tools":["state_expert"],"dataset_id":"vlada_w1_coverage_aggregates","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_county_payer_landscape","provenance_chain_ref":null,"known_gaps":["Coverage of extracted payers only."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"vlada_w1_coverage_aggregates","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["census:county_fips"],"entity_key_columns":{"census:county_fips":["county_fips"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.agg_state_payer_roster","provenance_chain_ref":null,"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_agg_state","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_policy_document","provenance_chain_ref":null,"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_policy_document","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["doc_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): vlada_curated.fact_policy_doc_chunk","provenance_chain_ref":null,"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_policy_doc","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"derived","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["doc_id"],"backing_store":"glue"},{"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":"retired","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,plan_id,segment_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","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,"superseded_by":"medicare_silver.ma_landscape_member_ledger (stamped re-collection 2026-09-07: same rows plus the provenance envelope (source_url, sha256_content_hash, asserted_at); the legacy table stays queryable until dropped)","tools":[],"dataset_id":"ds_medicare_landscape","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_ma_landscape_member_ledger","source_fqn":"medicare_silver.ma_landscape_member_ledger","title":"CMS MA / Part D Landscape member ledger (one row per publisher CSV member parsed)","domain":"medicare","stage":"silver","status":"live","grain":"One row per parsed CSV member per report_year: member name, sha256, header signature, mapping applied, ignored columns, rows parsed/skipped; 169 members on 2026-09-07.","description":"The parse ledger behind fact_ma_landscape: which publisher file member produced which year and category, under which header signature, with the exact header-to-column mapping applied. Read it to explain any Landscape number back to its file.","identity_key":"contract_id,plan_id,segment_id","row_count":169,"last_updated":"2026-09-07","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' follows fact_ma_landscape; one ledger row per parsed member per report_year."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_landscape_member_ledger","commercial_terms":"Public CMS data.","provenance_chain_ref":"pipelines/medicare/ingest/ma_landscape_runner.py; written in the same commit as fact_ma_landscape","context_doc_path":"docs/context_library/medicare/ma_landscape.md","known_gaps":["18 members of the CY2006-CY2025 bundle are skipped by design (plan-and-premium duplicates and non-data members); they are listed as skipped, not silently dropped."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_landscape","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_fact_ma_landscape_edition","source_fqn":"medicare_silver.fact_ma_landscape_edition","title":"CMS MA / Part D Landscape, EVERY edition held (Wayback originals + revisions + served copy), one partition per publisher zip","domain":"medicare","stage":"silver","status":"live","grain":"One row per edition x report_year x record_family x category x plan (contract, plan, segment) as published; natural key (edition, report_year, row_seq); 24 editions, 4,034,483 landscape rows (6,066,778 incl. plan-and-premium rows) on 2026-09-08.","description":"Sibling of fact_ma_landscape (which holds ONE edition per report_year: the copy CMS serves today, a REVISED bundle for CY2006-CY2025 with the star column re-stamped and sanctioned rows removed). This table holds every edition we have of a year side by side: the original September publication captured from the Wayback Machine (22 zips, CY2021-CY2026, bronze initial_editions/ with SHA-256), each mid-year revision, and the served copy. edition = the publisher zip stem (cy2026-landscape-202509 = the original CY2026 file of Sept 2025; cy2026-landscape-202608 = the Aug 2026 revision; cy2006-cy2025-landscape-files = the served bundle). Same columns as fact_ma_landscape plus edition; strings as published, cast on read. Use for what the market saw on Landscape day and the original-vs-revised diff; use fact_ma_landscape for the single served view.","identity_key":"contract_id,plan_id,segment_id","row_count":6066778,"last_updated":"2026-09-08","freshness_sla":"Event-driven (a new CMS revision or Wayback capture = one more zip under bronze initial_editions/ + a manifest line + one more partition).","recollection":{"cadence":"event_driven","watermark_field":"edition","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["A replace of one edition partition never touches another edition or fact_ma_landscape."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ma_landscape_edition","commercial_terms":"Public CMS data (Wayback Machine captures of CMS-published zips).","provenance_chain_ref":"pipelines/medicare/ingest/ma_landscape_edition_runner.py (job build_medicare_ma_landscape_editions) from s3://vlada-platform-raw/medicare/bronze/cms_ma_landscape/initial_editions/manifest.jsonl (22 SHA-verified originals) + the held zips under the same prefix; edition inventory docs/knowledge/ma/landscape-editions-ledger.md; parse ledger medicare_silver.ma_landscape_edition_ledger","context_doc_path":"docs/context_library/medicare/ma_landscape.md","known_gaps":["Originals exist only from CY2021 (Wayback has no earlier September captures found); CY2006-CY2020 are present only as the served revised bundle.","asserted_at is the load date (2026-09-08), not the publisher's publication date; the publication month is in the edition label, the first Wayback capture in the editions ledger."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_landscape","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_ma_landscape_edition_ledger","source_fqn":"medicare_silver.ma_landscape_edition_ledger","title":"CMS MA / Part D Landscape edition ledger (one row per publisher CSV member parsed, per edition)","domain":"medicare","stage":"silver","status":"live","grain":"One row per edition x parsed CSV member: member name, sha256, header signature, mapping applied, ignored columns, rows parsed/skipped; 276 members on 2026-09-08.","description":"The parse ledger behind fact_ma_landscape_edition: which member of which edition zip produced which year and category, under which header signature (47 signatures in pipelines/medicare/silver/ma_landscape_contracts.yaml, 9 of them seen only in original editions), with the exact header-to-column mapping applied.","identity_key":"contract_id,plan_id,segment_id","row_count":276,"last_updated":"2026-09-08","freshness_sla":"Event-driven (with fact_ma_landscape_edition).","recollection":{"cadence":"event_driven","watermark_field":"edition","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["One row per edition x member; a replace of one edition partition never touches another edition."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ma_landscape_edition_ledger","commercial_terms":"Public CMS data.","provenance_chain_ref":"pipelines/medicare/ingest/ma_landscape_edition_runner.py; written in the same commit as fact_ma_landscape_edition","context_doc_path":"docs/context_library/medicare/ma_landscape.md","known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_landscape","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,plan_id,segment_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","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,"superseded_by":null,"tools":[],"dataset_id":"cms_ma_plan_finder_mpf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:contract_id","cms:plan_id","cms:segment_id"],"entity_key_columns":{"cms:contract_id":["contract_id"],"cms:plan_id":["plan_id"],"cms:segment_id":["segment_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":null,"last_updated":null,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_dmf","notes":null,"superseded_by":null,"tools":[],"dataset_id":"fda_drug_master_files","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["dmf_number"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_clinical_trial","notes":null,"superseded_by":null,"tools":[],"dataset_id":"nlm_clinicaltrials_gov","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["nct_id"],"backing_store":"glue"},{"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":10564656,"last_updated":"2026-07-26","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 at 10,564,656 service-code rows (re-measured 2026-07-26 after the 2020-2024 refresh; the prior catalog figure of 10,554,124 was the pre-refresh count). The SIX-table EFAST2 family totals 32,402,086 rows.","This sidecar is the only one of the six Form 5500 tables that is NOT source-certified; its claim ceiling is queryable. The other five carry product1-source-acceptance/v1 artifacts.","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.","superseded_by":null,"tools":[],"dataset_id":"dol_form5500_efast2","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["ack_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_provider_ownership","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.","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"cms_pecos_all_owners","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["enrollment_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospital_service_area","notes":"Iceberg table medicare_silver.fact_hospital_service_area, partitioned by data_year (replace per year, idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_hospital_service_area","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_medicare_geo_variation","notes":"Iceberg table medicare_silver.fact_medicare_geo_variation, partitioned by year (replace per year, single source file with an in-row YEAR column).","superseded_by":null,"tools":[],"dataset_id":"cms_geographic_variation_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["bene_geo_code"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hrrp","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>.","superseded_by":null,"tools":["get_hospital_quality"],"dataset_id":"cms_hrrp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":["fiscal_year","measure_name"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hvbp","notes":"Iceberg medicare_silver.fact_hvbp, partition by fiscal_year, replace (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_hvbp","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hacrp","source_fqn":"medicare_silver.fact_hacrp","title":"CMS Hospital-Acquired Condition Reduction Program (HACRP)","domain":"hospital","stage":"silver","status":"live","grain":"One row per (fiscal_year, hospital CCN) with PSI-90, five HAI measures, Total HAC Score, and payment-reduction status.","description":"The CMS HAC Reduction Program hospital file. It carries PSI-90, CLABSI, CAUTI, SSI, CDI, and MRSA values and standardized scores, the Total HAC Score, and whether the hospital receives the one-percent Medicare payment reduction.","identity_key":"fiscal_year,ccn","row_count":3055,"last_updated":"2026-08-08","raw_queryable_via":"Athena (read-only): medicare_silver.fact_hacrp","notes":"FY2026 is live at 3055 rows and 3055 unique CCNs with zero duplicate FY+CCN keys or required-lineage nulls. Exact replay returned IDEMPOTENT_SKIP. Current rows overlap 3045 hospital-quality CCNs and 3050 hospital-price-spine CCNs.","superseded_by":null,"tools":[],"dataset_id":"ds_cms_hacrp","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":["fiscal_year"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_esrd_qip","notes":"Iceberg medicare_silver.fact_esrd_qip, partition by payment_year, replace (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_esrd_qip","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_dialysis_facility_quality","notes":"Iceberg medicare_silver.dim_dialysis_facility_quality, partition by state, replace (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_care_compare_dialysis","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"cms_pecos_public_provider_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":[],"dataset_id":"cms_pecos_public_provider_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"retired","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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ncci_ptp","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.","superseded_by":"medicare_silver.ref_ncci_ptp_edit (stamped re-collection 2026-09-07: every quarterly edition, both settings, deleted pairs kept with their deletion dates; filter deletion_date IS NULL for the active set)","tools":[],"dataset_id":"ds_cms_ncci","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["column_1_code"],"backing_store":"glue"},{"source_id":"cms_ncci_ptp_edit_editions","source_fqn":"medicare_silver.ref_ncci_ptp_edit","title":"CMS NCCI Procedure-to-Procedure (PTP) edits — quarterly editions, practitioner and hospital, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per (edition, setting, pair as published) including pairs carrying a deletion_date; natural key (edition, row_seq); 4,506,527 rows for 2026Q4 (practitioner 2,637,645 / hospital 1,868,882).","description":"CMS NCCI PTP edits re-collected through the provenance envelope on 2026-09-07: both settings, every pair as published with effective and deletion dates, modifier indicator and rationale. Filter deletion_date IS NULL for the active edit set (the legacy ncci_ptp was that active practitioner set for one quarter). CPT descriptors are not stored (AMA license accepted openly; the license page is kept in bronze).","identity_key":"column_1_code","row_count":4506527,"last_updated":"2026-09-07","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ref_ncci_ptp_edit","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ncci_ptp_edits","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["column_1_code"],"backing_store":"glue"},{"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).","superseded_by":null,"tools":[],"dataset_id":"cms_pfs_relative_value_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_physician_other_practitioners","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["rndrng_npi"],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_inpatient_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_outpatient_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","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).","superseded_by":null,"tools":[],"dataset_id":"cms_puf_dme_devices_supplies","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["suplr_npi"],"backing_store":"glue"},{"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":7515432,"last_updated":"2026-09-23","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","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, two collections: 2018 (967,129 rows, 1,013 codes; set CY2021-2026 rates) and 2026 (6,548,303 rows, 1,528 codes; sets CY2027 rates, loaded 2026-09-23 through the PAMA runner and reconciled per code to CMS's CSV). Many rows per HCPCS; always filter collection_year and aggregate (e.g. weighted median) per hcpcs_cd for a single benchmark.","The 2026 file's column names differ (Payment_Rate, Volume); the parser maps them to the same two columns. Identical rows are separate observations (row_seq keeps them).","Codes reported by fewer than 10 TINs are withheld by CMS by statute.","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.","superseded_by":null,"tools":[],"dataset_id":"cms_clfs_pama_private_payer_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_clfs_private_payer_rate_2026collection","source_fqn":"medicare_silver.fact_clfs_private_payer_rate_2026collection","title":"Medicare CLFS Private Payer Rates and Volumes (PAMA), 2026 collection (sets CY2027 rates)","domain":"medicare","stage":"silver","status":"retired","grain":"One row per reported private-payer rate/volume observation (collection_year 2026), keyed to HCPCS; no row_seq, many rows per hcpcs_cd.","description":"The 2026 PAMA data collection: 6,548,302 private-payer rate and volume observations across 1,528 HCPCS codes, the observations behind CMS's preliminary CY2027 CLFS rates (published 2026-09-21). Codes reported by fewer than 10 TINs are withheld by CMS by statute. Landed 2026-09-22 as its own table; the 2018 collection is medicare_silver.fact_clfs_private_payer_rate.","identity_key":"hcpcs_cd","row_count":6548302,"last_updated":"2026-09-22","freshness_sla":"Per PAMA data-collection cycle (every 3 years); this is the 2026 cycle.","recollection":{"cadence":"derived","watermark_field":"collection_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["collection_year is the PAMA data-collection cycle year (2026); the rates it sets are CY2027."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_clfs_private_payer_rate_2026collection","provenance_chain_ref":"medicare/bronze/cms_clfs_pama_private_payer_rates/cy2027_preliminary_20260921/manifest.json (sha256 per artifact; every row carries source_url + sha256_content_hash + asserted_at).","context_doc_path":"docs/context_library/medicare/clfs_pama_2027_preliminary.md","known_gaps":["RAW per-observation rows; aggregate (weighted median) per hcpcs_cd for a benchmark, never read one row as the rate.","volume_text is text (may be ranges); private_payer_rate is the reported rate amount.","Loaded by a one-off CTAS from the CMS CSV on 2026-09-22, not by the PAMA runner; not merged into fact_clfs_private_payer_rate (which holds the 2018 collection with row_seq).","ONE ROW SHORT (measured 2026-09-23 against the CMS CSV, 6,548,303 rows) - the CTAS dropped the file's first data row, 0001U at $1,872.58 volume 1 (Athena 9f4b2530). Every other code's row count matches. Identical rows are real separate observations (3,549,528 rows in 766,842 identical groups, same as the file).","SUPERSEDED 2026-09-23 - use medicare_silver.fact_clfs_private_payer_rate WHERE collection_year = 2026, which holds all 6,548,303 rows keyed by row_seq (Athena decad0cf). This table stays readable until its retirement is decided."],"notes":"Iceberg, one collection_year (2026). Source bytes s3://vlada-platform-raw/medicare/bronze/cms_clfs_pama_private_payer_rates/cy2027_preliminary_20260921/.","superseded_by":"medicare_silver.fact_clfs_private_payer_rate WHERE collection_year = 2026 (loaded 2026-09-23 through the PAMA runner: all 6,548,303 rows keyed by row_seq, reconciled per code to the CMS CSV; this one-off CTAS table is one row short). Retired from the register 2026-09-23 on Ben's decision; the table stays in Glue until dropped.","tools":[],"dataset_id":"cms_clfs_pama_private_payer_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_clfs_preliminary_rate","source_fqn":"medicare_silver.fact_clfs_preliminary_rate","title":"Medicare CLFS preliminary CY2027 rates (PAMA weighted medians, raw vs trimmed, capped)","domain":"medicare","stage":"silver","status":"live","grain":"One row per HCPCS code in CMS's preliminary CY2027 CLFS rate calculation file (rate_year, hcpcs_code).","description":"CMS's preliminary CY2027 Clinical Laboratory Fee Schedule per code: the 2026 CLFS rate, the raw and trimmed private-payor weighted medians, the percent change, the reporting-TIN count (withheld under 10), and the CY2027 rate after the 15% payment-reduction cap. Published 2026-09-21; comment window 30 days; final rates post November 2026 and supersede this edition.","identity_key":"hcpcs_code","row_count":1924,"last_updated":"2026-09-22","freshness_sla":"Annual; preliminary in late September, final in November (stage column says which).","recollection":{"cadence":"annual","watermark_field":"rate_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["rate_year is the year the rates apply (2027); collection_year is the PAMA cycle (2026); stage distinguishes preliminary from final."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_clfs_preliminary_rate","provenance_chain_ref":"medicare/bronze/cms_clfs_pama_private_payer_rates/cy2027_preliminary_20260921/manifest.json (sha256 per artifact; every row carries source_url + sha256_content_hash + asserted_at).","context_doc_path":"docs/context_library/medicare/clfs_pama_2027_preliminary.md","known_gaps":["PRELIMINARY (stage='preliminary'); the final CY2027 rates replace this edition in November 2026.","414 of 1,924 codes have no 2026 rate or no 2027 rate (new, crosswalked, or unpriced); rate_2027_preliminary is null there, never zero.","reporting_tins_text is text; a non-numeric value means CMS withheld the count (fewer than 10 TINs, 787 codes).","The 23 Pap smear codes CMS marks with an asterisk (88142-88175, G0123, G0143-G0148, P3000, Q0111, Q0115) are ABSENT - CMS's file lists 1,947 codes, this table 1,924. Their rates are set under section 1833(h)(7), not by PAMA, so the file carries no 2027 rate for them; absence here does not mean the code is unpriced (measured 2026-09-23)."],"notes":"Iceberg, one edition (rate_year 2027, stage preliminary). Loaded 2026-09-22 by CTAS from the CMS HCPCS_Prelim_Wgt_Meds_Simple tab.","superseded_by":null,"tools":[],"dataset_id":"cms_clfs_pama_private_payer_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_market_saturation","notes":"Iceberg medicare_silver.fact_market_saturation, partition by reference_period, replace (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_market_saturation_utilization","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["census:county_fips"],"entity_key_columns":{"census:county_fips":["county_fips"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":44429,"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","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); 37 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)."],"notes":"Iceberg medicare_silver.fact_provider_of_services, partition by data_year, replace (idempotent by SHA-256).","superseded_by":null,"tools":[],"dataset_id":"cms_provider_of_services_file","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["prvdr_num"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_post_acute_utilization","notes":"Iceberg medicare_silver.fact_post_acute_utilization, partitioned by (setting, year) so each setting-year CSV is its own replace-safe partition.","superseded_by":null,"tools":[],"dataset_id":"cms_puf_post_acute_care","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["prvdr_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_aco_participant","notes":"Iceberg medicare_silver.fact_aco_participant, partition by performance_year, replace.","superseded_by":null,"tools":[],"dataset_id":"cms_mssp_aco_participants","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["aco_id"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.dim_mdpp_supplier","notes":"Iceberg medicare_silver.dim_mdpp_supplier, partition by state, replace.","superseded_by":null,"tools":[],"dataset_id":"cms_mdpp_suppliers","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_qpp_experience","notes":"Iceberg medicare_silver.fact_qpp_experience, partition by data_year, replace.","superseded_by":null,"tools":[],"dataset_id":"cms_qpp_experience","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_medicaid_managed_care","notes":"Iceberg medicare_silver.fact_medicaid_managed_care, partition by calendar_year, replace.","superseded_by":null,"tools":["get_medicaid_mco_enrollment"],"dataset_id":"cms_medicaid_managed_care_utilization_by_mco","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["mco_name"],"backing_store":"glue"},{"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) OON Emergency and Non-Emergency line-item PUF. It reports who prevailed and provider, plan, and prevailing offers as a percentage of QPA by service code, place of service, location, specialty, practice size, and plan type. Air Ambulance and QPA/Offers are separate accepted grains.","identity_key":"provider_npi","row_count":8233903,"last_updated":"2026-07-22","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).","known_gaps":["HEAVY: 2025Q3/Q4 ZIPs exceed 600MB/1.2GB; full backfill runs only on the compute fleet (job_type build_idr_determination).","Excel percentage-formatted numeric cells are stored as fractions; parser v2 converts raw 1.64 with a percent format to 164 percentage points. Never apply another x100.","Offer percentages can legitimately exceed 100%; explicit analytics flags quarantine implausible values without deleting raw/source-status evidence."],"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.","superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["nppes:npi"],"entity_key_columns":{"nppes:npi":["provider_npi"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_psps","notes":"Iceberg medicare_silver.fact_psps, partition by data_year; bulk-load (append_buffered 300k -> flush per year).","superseded_by":null,"tools":[],"dataset_id":"cms_psps","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_drug_discarded_units","notes":"Iceberg drug_silver.fact_drug_discarded_units, partition by data_year, replace.","superseded_by":null,"tools":[],"dataset_id":"cms_part_b_discarded_drug_units","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_cd"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_tc_puf_issuer_claims","source_fqn":"medicare_silver.fact_tc_puf_issuer_claims","title":"CMS Transparency in QHP Coverage PUF — partial Individual QHP serving derivative","domain":"commercial","stage":"silver","status":"live","grain":"Partial table: one Individual-QHP row per (publication-year label stored as plan_year, 14-character Plan_ID); issuer-level measures repeat across plan rows.","description":"A 25,666-row partial derivative of the CMS CCIIO Transparency in QHP Coverage PUF: only the Individual QHP tabs from publication years 2022-2026. Those publications contain measurement data from 2020-2024 respectively. Do not treat plan_year as the measure year, aggregate repeated issuer measures across plans, or publish payer rankings until denominator and suppression semantics pass review.","identity_key":"plan_year,plan_id","row_count":25666,"last_updated":null,"freshness_sla":"Annual publication; measures lag the publication label by two years.","recollection":{"cadence":"annual","watermark_field":"plan_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'plan_year' stores the PUF publication label, not the claims/enrollment measurement year; data_year = plan_year - 2."]},"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":["The official family has 40,222 data rows across PY2017-2026; 14,556 are outside this table (all PY2017-2021 rows plus PY2022-2026 Individual SADP/SHOP rows).","PY2017-2019 are issuer-level without Plan_ID; PY2020 is a mixed plan-level sheet without explicit market/dental scope. They cannot be appended to this table honestly.","PY2023 Individual SADP contains three non-identical duplicate plan keys; the lossless source key requires sheet and source-row identity.","Suppressed cells (* / ** / *** / N/A) were coerced to null in this derivative. They are distinct source states, not zero.","Issuer measures repeat across plan rows; denominator-safe semantic views are acceptance-gated."],"notes":"Iceberg table remains live and unchanged. The canonical manifest-driven runner is now no-write certification only; production execution is disabled pending a lossless history writer and semantic review.","superseded_by":null,"tools":[],"dataset_id":"cms_cciio_transparency_in_coverage_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:plan_id"],"entity_key_columns":{"cms:plan_id":["plan_id"]},"technical_keys":["plan_year"],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hpsa","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.","superseded_by":null,"tools":[],"dataset_id":"hrsa_hpsa_designations","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["discipline","row_seq"],"backing_store":"glue"},{"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","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.dim_device_udi","notes":"Iceberg drug_silver.dim_device_udi, partition by release_month; bulk-load (append_buffered 300k -> flush).","superseded_by":null,"tools":[],"dataset_id":"nlm_accessgudid","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["primary_di"],"backing_store":"glue"},{"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":32902283,"last_updated":null,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_rate_puf","notes":"Iceberg medicare_silver.fact_rate_puf, partition by business_year; bulk-load. row_seq keys each row.","superseded_by":null,"tools":["get_exchange_plan_profile"],"dataset_id":"cms_cciio_rate_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["issuer_id"],"backing_store":"glue"},{"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","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.","superseded_by":null,"tools":["get_hospital_quality"],"dataset_id":"cms_care_compare_hospitals","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospice_quality","notes":"Iceberg medicare_silver.fact_hospice_quality, partition by reporting_year, replace. Join ccn to dim_hospice.","superseded_by":null,"tools":[],"dataset_id":"cms_care_compare_hospice","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"state_medicaid_fee_schedules","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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","raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"notes":null,"superseded_by":null,"tools":[],"dataset_id":"md_hscrc_unit_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ma_chia_relative_price","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_home_health_quality","notes":"Iceberg medicare_silver.fact_home_health_quality, partition by reporting_year, replace. Join ccn to dim_hha.","superseded_by":null,"tools":[],"dataset_id":"cms_care_compare_home_health","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_nursing_home_quality","notes":"Iceberg medicare_silver.fact_nursing_home_quality, partition by reporting_year, replace. Join ccn to dim_snf.","superseded_by":null,"tools":[],"dataset_id":"cms_care_compare_nursing_homes","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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":"One row per line of a quarter's FAERS DRUG file: physical key (report_quarter, row_seq), row_seq = the line's position in that quarter's file (accepted 2026-09-23). (report_quarter, primaryid, drug_seq) is NOT a key: the publisher repeats it (21,797 duplicate groups / 68,550 rows in 2025Q1). Quarters are noncumulative and case-versioned; count cases with the current-case rule in the context doc, never rows or distinct primaryid.","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). ~1.6-2.2M rows/quarter; 2025Q1-2026Q2 loaded (six quarters).","identity_key":"report_quarter,row_seq","row_count":11131453,"last_updated":"2026-09-23","raw_queryable_via":"Athena (read-only via query_substrate): drug_silver.fact_faers_drug","notes":"Iceberg drug_silver.fact_faers_drug, partition by report_quarter; bulk-load (append_buffered 300k -> flush_buffered_replace_partitions); a rerun of a loaded quarter skips on the ZIP SHA-256 recorded in medicare_source_registry_cache.","superseded_by":null,"tools":[],"dataset_id":"fda_faers","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["report_quarter","row_seq"],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ct_dss_medicaid_hospital_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ct_dss_medicaid_hospital_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ambulance_fee_schedule","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.","superseded_by":null,"tools":[],"dataset_id":"cms_ambulance_fee_schedule","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"md_hscrc_monthly_revenue_volume","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ma_chia_hospital_financial_performance","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hospice_pps_rate","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.","superseded_by":null,"tools":[],"dataset_id":"cms_hospice_pps_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["level_of_care"],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"context_doc_path":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ct_ohs_hospital_cost_to_charge","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_irf_pps_cmg_weight","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.","superseded_by":null,"tools":[],"dataset_id":"cms_irf_pps_cmg_weights","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["cmg"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_hh_pdgm_weight","notes":"Iceberg medicare_silver.fact_hh_pdgm_weight, partition by calendar_year, replace. Source = CMS HH PPS Case-Mix Weights annual zip.","superseded_by":null,"tools":[],"dataset_id":"cms_home_health_pdgm_weights","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["hipps"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_fqhc_pps_rate","notes":"Iceberg medicare_silver.fact_fqhc_pps_rate, partition by calendar_year, replace. Source = CMS Pricer-update transmittal PDF (validated extraction).","superseded_by":null,"tools":[],"dataset_id":"cms_fqhc_pps_rate","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["calendar_year"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_snf_pdpm_rate","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.","superseded_by":null,"tools":[],"dataset_id":"cms_snf_pdpm_rates","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["pdpm_group"],"backing_store":"glue"},{"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,"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ltch_pps_drg_weight","notes":"Iceberg medicare_silver.fact_ltch_pps_drg_weight, partition by fiscal_year, replace. Source = CMS MS-LTC-DRG File (Table 11) zip.","superseded_by":null,"tools":[],"dataset_id":"cms_ltch_pps_drg_weights","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["ms_ltc_drg"],"backing_store":"glue"},{"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,"raw_queryable_via":null,"commercial_terms":null,"provenance_chain_ref":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"nj_doh_hospital_financials","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_insurer_mlr","source_fqn":"insurer_silver.fact_insurer_mlr","title":"Commercial Insurer MLR — financial facts (CMS MLR PUF)","domain":"commercial","stage":"silver","status":"live","grain":"One row per (business_year, mr_submission_template_id, market). Wide pivot — premium_earned, incurred_claims, member_months per issuer submission x market. 19,141 rows across 2019-2024.","description":"The commercial insurer P&L: filed premium earned, incurred claims, and member-months per issuer submission x market (individual/small_group/large_group/...), from the CMS Medical Loss Ratio PUF. Join dim_insurer_mlr_identity on mr_submission_template_id for the NAIC crosswalk + brand. loss_ratio = incurred_claims/premium_earned. The insurer-economics side of the Payers/Investors wedge.","identity_key":"business_year,mr_submission_template_id,market","row_count":19141,"last_updated":"2026-07-17","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'business_year' is the MLR reporting year of the filing, one CMS PUF ZIP per year (2019-2024 held; 2011-2018 have irregular publisher URLs and are not loaded).","is_current is false on every physical history row by writer contract; currentness is answered by insurer_silver.vw_insurer_mlr_current (highest cms_vintage_sequence per key), never by WHERE is_current.","A re-ingest of a business_year is a supersession-replace of that year.","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): insurer_silver.fact_insurer_mlr","provenance_chain_ref":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_cms_insurer","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year"],"unmapped_key_tokens":["market","mr_submission_template_id"],"backing_store":"glue"},{"source_id":"cms_insurer_mlr_identity","source_fqn":"insurer_silver.dim_insurer_mlr_identity","title":"Commercial Insurer MLR — issuer identity / NAIC crosswalk (CMS MLR PUF)","domain":"commercial","stage":"silver","status":"live","grain":"One row per (business_year, mr_submission_template_id). Issuer identity + the free NAIC crosswalk. 14,600 rows across 2019-2024.","description":"The free entity crosswalk the CMS MLR PUF carries: hios_issuer_id, naic_group_code, naic_company_code, federal_ein, company_name, group_affiliation, dba_marketing_name per submission. Resolves an MLR financial filing to a payer BRAND + NAIC — the join key connecting insurer financials to negotiated rates (dim_payer).","identity_key":"business_year,mr_submission_template_id","row_count":14600,"last_updated":"2026-07-17","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'business_year' is the MLR reporting year of the submission the identity row was filed with; identity can change year to year (rebrands, group moves), so join the facts on (business_year, mr_submission_template_id).","business_state = 'Grand Total' is a publisher rollup row that double-counts if kept; vw_insurer_mlr_current excludes it.","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): insurer_silver.dim_insurer_mlr_identity","provenance_chain_ref":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_cms_insurer","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year"],"unmapped_key_tokens":["mr_submission_template_id"],"backing_store":"glue"},{"source_id":"cms_transparency_in_coverage_puf","source_fqn":"medicare_silver.fact_transparency_in_coverage_puf_history","title":"CMS CCIIO Transparency in Coverage PUF — QHP claims transparency (multi-sheet XLSX)","domain":"commercial","stage":"silver","status":"live","grain":"One publisher row per (business_year, market_segment, sheet source_row_number). 3 market segments (Ind QHP / Ind SADP / SHOP), lossless multi-sheet XLSX stored as ordered_header_json + raw_values_json. 40,222 rows across PY2017-2026.","description":"Per issuer x plan claims transparency (received / denied / resubmitted, in- and out-of-network) from the CMS Transparency in Coverage PUF, across all 3 market-segment sheets (Ind QHP / Ind SADP / SHOP) plus the legacy 2017-2020 combined sheet. Lossless: raw cells preserved in ordered_header_json + raw_values_json with a market_segment dimension. Payer-behavior signal.","identity_key":"business_year,market_segment,source_row_number","row_count":40222,"last_updated":"2026-07-17","freshness_sla":"Annual plan-year publication.","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'business_year' is the publication plan-year label of the annual workbook; the claims and enrollment it reports were measured two years earlier (data_year = business_year - 2, verified 2026-09-04: PY2026 reports PY2024 data).","A new plan-year workbook is appended as a new immutable artifact (source_zip_sha256); changed bytes at the same URL coexist as another artifact, never an overwrite.","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.fact_transparency_in_coverage_puf_history","commercial_terms":"Public CMS/CCIIO data.","provenance_chain_ref":null,"context_doc_path":"docs/context_library/commercial/transparency_in_coverage_puf.md","known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cciio_transparency_in_coverage_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year","source_row_number"],"unmapped_key_tokens":["market_segment"],"backing_store":"glue"},{"source_id":"cms_quality_puf","source_fqn":"medicare_silver.fact_quality_puf_history","title":"CMS CCIIO Quality PUF — Marketplace QHP quality star ratings","domain":"commercial","stage":"silver","status":"live","grain":"One publisher row per (business_year, source_row_number); lossless CSV/XLSX stored as ordered_header_json + raw_values_json. 16,075 rows PY2023/2024/2026.","description":"The CMS Marketplace Quality PUF — QHP quality star ratings assigned to plans on HealthCare.gov, per issuer x plan. Lossless hybrid CSV/XLSX. The quality dimension of the exchange plan graph.","identity_key":"business_year,source_row_number","row_count":16075,"last_updated":"2026-07-17","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_quality_puf_history","provenance_chain_ref":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cciio_quality_puf","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["business_year","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_exchange_plan_profile","source_fqn":"medicare_silver.fact_exchange_plan_profile","title":"Exchange Plan Profile — composed ACA marketplace plan brain","domain":"commercial","stage":"silver","status":"live","grain":"One row per (business_year, plan_id). 60,591 plan-years PY2014-2026. Materialized composition of six verified exchange PUF sources at plan grain (zero fanout).","description":"The composed \"plan brain\" for the ACA marketplace: one row per plan-year carrying its full vector — attributes (metal/type/on-off-exchange/issuer/TIN) from Plan Attributes, premium benchmarks (age 21/40/60 x rating area) from Rate, network name from Network, county footprint from Service Area, covered-benefit counts + headline cost-shares (PCP/specialist/ER/urgent/generic/inpatient) from Benefits & Cost Sharing, CMS star ratings from Marketplace Quality, and the issuer's individual-market financials (premium earned + MLR ratio) from the CMS MLR PUF. Joins measured/verified (Plan Attributes->Rate 100%; per-plan end-to-end proven); materialized so plan lookups serve fast (no parse-in-view cliff).","identity_key":"business_year,plan_id","row_count":60591,"last_updated":"2026-07-17","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_exchange_plan_profile","provenance_chain_ref":null,"known_gaps":[],"notes":null,"superseded_by":null,"tools":["get_exchange_plan_profile"],"dataset_id":"vlada_w4_exchange_plan_profile","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:plan_id"],"entity_key_columns":{"cms:plan_id":["plan_id"]},"technical_keys":["business_year"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_idr_air_ambulance","source_fqn":"medicare_silver.fact_idr_air_ambulance_determination","title":"CMS Federal IDR Air Ambulance determinations","domain":"commercial","stage":"silver","status":"live","grain":"One row per air-ambulance dispute line item (year, quarter, row_seq).","description":"The official Air Ambulance tab of each Federal IDR PUF, preserved as its own line-item grain with air vehicle, service, party, offer, QPA, raw-value/status, quality, and M-2 lineage fields.","identity_key":"dli_number","row_count":104383,"last_updated":"2026-07-22","freshness_sla":"Quarterly (CMS No Surprises reports page).","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_air_ambulance_determination","commercial_terms":"Public CMS data; freely redistributable per the PUF user agreement.","provenance_chain_ref":"Content-addressed CMS Bronze object plus M-2 row lineage.","known_gaps":["Raw publisher percentage values above 100,000 percentage points are retained but explicitly flagged and excluded from analytics eligibility."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["dli_number"],"backing_store":"glue"},{"source_id":"cms_idr_qpa_offers","source_fqn":"medicare_silver.fact_idr_qpa_offer","title":"CMS Federal IDR QPA and offers","domain":"commercial","stage":"silver","status":"live","grain":"One row per published QPA/offer observation (year, quarter, row_seq); early workbooks do not expose dispute/DLI identifiers on this tab.","description":"The official QPA and Offers tab, separated from determination line items because its publisher grain and historical identifiers differ. Carries service, geography/POS, QPA, provider/plan/prevailing offers, selected/default indicators, raw-value/status, and M-2 lineage.","identity_key":"service_code","row_count":11346219,"last_updated":"2026-07-22","freshness_sla":"Quarterly (CMS No Surprises reports page).","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_qpa_offer","commercial_terms":"Public CMS data; freely redistributable per the PUF user agreement.","provenance_chain_ref":"Content-addressed CMS Bronze object plus M-2 row lineage.","known_gaps":["Do not manufacture joins to dispute IDs where CMS did not publish them; early QPA/Offers tabs are independently grained observations."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["service_code"],"backing_store":"glue"},{"source_id":"cms_idr_supplemental_summary","source_fqn":"medicare_silver.fact_idr_supplemental_summary","title":"CMS Federal IDR Supplemental summary and outcome tables","domain":"commercial","stage":"silver","status":"live","grain":"One row per quarterly published metric in Supplemental Tables 1-6 and 12.","description":"Quarterly Federal IDR aggregate initiations, eligibility challenges, closure reasons, program expenditures/fees/compensation, and determination outcomes, with emergency/non-emergency, air-ambulance, and total values kept distinct.","identity_key":"metric_name","row_count":409,"last_updated":"2026-07-22","freshness_sla":"Quarterly.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_supplemental_summary","commercial_terms":"Public CMS data.","provenance_chain_ref":"Content-addressed CMS Bronze workbook plus M-2 row lineage.","known_gaps":["Tables begin 2023Q1; the 2022 status/interim PDFs are separate narrative publications, not this 14-table source family."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["metric_name"],"backing_store":"glue"},{"source_id":"cms_idr_supplemental_state","source_fqn":"medicare_silver.fact_idr_supplemental_state","title":"CMS Federal IDR Supplemental initiations by state","domain":"commercial","stage":"silver","status":"live","grain":"One row per (year, quarter, state or territory) from Supplemental Table 7.","description":"Federal IDR dispute initiations by service category and state/territory. The CMS plus-sign state-law/all-payer-model footnote is retained as an explicit indicator, not part of the state name.","identity_key":"state_or_territory","row_count":672,"last_updated":"2026-07-22","freshness_sla":"Quarterly.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_supplemental_state","commercial_terms":"Public CMS data.","provenance_chain_ref":"Content-addressed CMS Bronze workbook plus M-2 row lineage.","known_gaps":["State counts can sum above Table 1 because a batched dispute can contain services furnished in multiple states."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["state_or_territory"],"backing_store":"glue"},{"source_id":"cms_idr_supplemental_party","source_fqn":"medicare_silver.fact_idr_supplemental_party","title":"CMS Federal IDR Supplemental top disputing parties","domain":"commercial","stage":"silver","status":"live","grain":"One row per quarterly top-10 party/rank/service-category/party-role in Supplemental Tables 8-11.","description":"Top initiating and non-initiating parties or representatives for emergency/non-emergency and air ambulance disputes, including dispute share and health-plan-type subtotals where published.","identity_key":"party_or_representative","row_count":480,"last_updated":"2026-07-22","freshness_sla":"Quarterly.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_supplemental_party","commercial_terms":"Public CMS data.","provenance_chain_ref":"Content-addressed CMS Bronze workbook plus M-2 row lineage.","known_gaps":["CMS says email-domain aggregation may undercount or split parties; names are publisher groupings, not a canonical payer/provider identity bridge.","Two publisher subtotal inconsistencies are retained and flagged: 2023Q4 Table 9 Anthem (49,048 component sum vs 49,052 total) and 2024Q2 Table 9 BCBS Texas (28,229 vs 28,254)."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["party_or_representative"],"backing_store":"glue"},{"source_id":"cms_idr_supplemental_qpa_band","source_fqn":"medicare_silver.fact_idr_supplemental_qpa_band","title":"CMS Federal IDR prevailing offers by QPA cost band","domain":"commercial","stage":"silver","status":"live","grain":"One row per (year, quarter, QPA range) from Supplemental Table 13.","description":"Median prevailing offer as percentage of QPA plus determination and item/service counts by QPA cost band.","identity_key":"qpa_range","row_count":72,"last_updated":"2026-07-22","freshness_sla":"Quarterly.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_supplemental_qpa_band","commercial_terms":"Public CMS data.","provenance_chain_ref":"Content-addressed CMS Bronze workbook plus M-2 row lineage.","known_gaps":["Median offer percentages are already percentage points; do not rescale values such as 532 to 5.32."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["qpa_range"],"backing_store":"glue"},{"source_id":"cms_idr_supplemental_specialty","source_fqn":"medicare_silver.fact_idr_supplemental_specialty","title":"CMS Federal IDR prevailing offers by specialty","domain":"commercial","stage":"silver","status":"live","grain":"One row per (year, quarter, CPT range, specialty) from Supplemental Table 14.","description":"Median prevailing offer as percentage of QPA and determination/item counts by CMS-published specialty/CPT band.","identity_key":"specialty","row_count":321,"last_updated":"2026-07-22","freshness_sla":"Quarterly.","recollection":{"cadence":"quarterly","watermark_field":"year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'year' is paired with quarter for the publisher's quarterly vintage."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_idr_supplemental_specialty","commercial_terms":"Public CMS data.","provenance_chain_ref":"Content-addressed CMS Bronze workbook plus M-2 row lineage.","known_gaps":["CPT ranges overlap in publisher categories; use the published specialty row as the grain and do not explode a range into codes without a dated code-set policy."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_federal_idr_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["specialty"],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_utilization","source_fqn":"medicare_silver.hospital_cost_report_utilization","title":"CMS HCRIS Hospital utilization (Worksheet S-3 Part I)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (source fiscal-year archive, report record, exact S-3 worksheet line).","description":"Lossless hospital and hospital-complex beds, bed days available, Title V/Medicare/Medicaid/all-patient days, FTEs, and discharges from Form 2552-10 Worksheet S-3 Part I.","identity_key":"ccn","row_count":2462442,"last_updated":"2026-07-22","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_utilization","commercial_terms":"Public CMS data.","provenance_chain_ref":"HOSP10FY archive in content-addressed Bronze plus exact worksheet/line and M-2 lineage.","known_gaps":["Form 2552-10 begins FY2010. Pre-2010/overlap 2552-96 history is a separate schema-era acceptance gate.","Program columns are utilization, not payer revenue."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_financial","source_fqn":"medicare_silver.hospital_cost_report_financial","title":"CMS HCRIS Hospital financial statements (Worksheets G-2/G-3)","domain":"medicare","stage":"silver","status":"live","grain":"One row per (source fiscal-year archive, report record, worksheet, exact worksheet line).","description":"Form 2552-10 G-2 patient revenue/operating expense and G-3 revenue/expense/income statement lines with exact source column amounts and formula-quality flags.","identity_key":"ccn","row_count":2486705,"last_updated":"2026-07-22","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_financial","commercial_terms":"Public CMS data.","provenance_chain_ref":"HOSP10FY archive in content-addressed Bronze plus exact worksheet/line and M-2 lineage.","known_gaps":["G-2 is revenue by facility/service category, not Medicare/Medicaid/Other payer revenue. Never infer a payer split from it."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_profile","source_fqn":"medicare_silver.hospital_cost_report_profile","title":"CMS HCRIS CCN-level hospital operating profile","domain":"medicare","stage":"silver","status":"live","grain":"One row per CMS report record, with an explicit latest-record flag per exact (CCN, fiscal-year-end).","description":"A usable CCN report profile built only from documented S-3 line 14 and G-2/G-3 total cells. Includes beds, patient days, discharges, ALOS, ADC, occupancy, gross/net patient revenue, operating expense, and income fields.","identity_key":"ccn","row_count":90680,"last_updated":"2026-07-22","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_profile","commercial_terms":"Public CMS data.","provenance_chain_ref":"HOSP10FY archive in content-addressed Bronze plus exact source formulas and M-2 lineage.","known_gaps":["revenue_by_payer_available is always false because S-3/G do not directly publish the American Hospital Directory-style Medicare/Medicaid/Other revenue split.","Use the separate hospital_cost_report_payer_revenue table for the public gross-revenue formula; it is not AHA Annual Survey net payer revenue.","ALOS equals total patient days divided by total discharges; ADC equals total patient days divided by inclusive report-period days. Keep report-period length constant when comparing."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_report","source_fqn":"medicare_silver.hospital_cost_report_report","title":"CMS HCRIS Hospital report ledger (RPT)","domain":"medicare","stage":"silver","status":"live","grain":"One physical RPT source row per (source fiscal-year archive, source row number), retaining all 18 CMS-published fields.","description":"Lossless Form 2552-10 report metadata and revision ledger, including CCN, NPI, report/fiscal dates, status, control type, provider type, CHOW and amended-report relationships, and the selected-profile flag.","identity_key":"rpt_rec_num","row_count":91827,"last_updated":"2026-07-23","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_report","commercial_terms":"Public CMS data.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_hcris_complete_cell_ledger_2026_07_22.json","known_gaps":["Form 2552-10 covers FY2010 forward; CMS-2552-96 is a separately gated schema era."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["rpt_rec_num"],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_numeric_cell","source_fqn":"medicare_silver.hospital_cost_report_numeric_cell","title":"CMS HCRIS Hospital complete numeric cell ledger (NMRC)","domain":"medicare","stage":"silver","status":"live","grain":"One physical NMRC source row per (source fiscal-year archive, source row number).","description":"Complete lossless Form 2552-10 numeric worksheet cells with exact report key, worksheet, line, column, raw value, nullable typed value, parse status, and M-2 lineage.","identity_key":"source_row_number","row_count":296823696,"last_updated":"2026-07-23","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_numeric_cell","commercial_terms":"Public CMS data.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_hcris_complete_cell_ledger_2026_07_22.json","known_gaps":["Alphanumeric or punctuation-bearing coordinates are valid source values; numeric convenience fields are null when a code is not purely numeric.","Blank or invalid numeric source values remain retained and flagged; they are never coerced to zero."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_alpha_cell","source_fqn":"medicare_silver.hospital_cost_report_alpha_cell","title":"CMS HCRIS Hospital complete alpha cell ledger (ALPHA)","domain":"medicare","stage":"silver","status":"live","grain":"One physical ALPHA source row per (source fiscal-year archive, source row number).","description":"Complete lossless Form 2552-10 text worksheet cells with exact report key, worksheet, line, column, raw text value, and M-2 lineage.","identity_key":"source_row_number","row_count":55578535,"last_updated":"2026-07-23","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_alpha_cell","commercial_terms":"Public CMS data.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_hcris_complete_cell_ledger_2026_07_22.json","known_gaps":["Raw text is retained exactly after CSV decoding; consumers must interpret worksheet-specific semantics rather than applying a global blank-value policy."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_hcris_hospital_payer_revenue","source_fqn":"medicare_silver.hospital_cost_report_payer_revenue","title":"CMS HCRIS Hospital gross patient revenue by payer","domain":"medicare","stage":"silver","status":"live","grain":"One row per CMS report record, with an explicit latest-record flag per exact (CCN, fiscal-year-end).","description":"Revision-bound public gross Medicare, Medicaid, Other, and total patient revenue derived from documented Form 2552-10 D-3, D Part V, S-10, and G-2 cells using a pinned American Hospital Directory formula version.","identity_key":"ccn","row_count":91827,"last_updated":"2026-07-23","freshness_sla":"Annual CMS HCRIS refresh.","recollection":{"cadence":"annual","watermark_field":"source_fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'source_fiscal_year' identifies the CMS HOSP10 annual source archive."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.hospital_cost_report_payer_revenue","commercial_terms":"Public CMS data; the formula reference is publicly documented.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_hcris_complete_cell_ledger_2026_07_22.json","known_gaps":["These are gross reported patient-revenue amounts, not AHA Annual Survey net payer revenue and not commercial contract terms.","Other is a residual and is published only when total, Medicare, and Medicaid inputs are all present; missing source cells remain null, never zero.","Formula version ahd_operational_2552_10_2023_05_07_v1 must be retained when comparing or refreshing rows."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_hcris_hospital_2552_10","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_mcd_document","source_fqn":"medicare_silver.mcd_document","title":"CMS Medicare Coverage Database public documents","domain":"medicare","stage":"silver","status":"live","grain":"One row per (Coverage API snapshot, public endpoint, publisher row ordinal) document or public local-document index record.","description":"Public no-license CMS Medicare coverage documents and report indexes, including national NCD/NCA/CAL history, MEDCAC and technology-assessment material, and current/future/retired local LCD and Article index metadata.","identity_key":"document_id","row_count":5365,"last_updated":"2026-07-23","freshness_sla":"Weekly CMS local-data refresh; national updates may occur more frequently.","recollection":{"cadence":"weekly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Current corpus is a versioned API snapshot; preserve document-level effective, implementation, retirement, and raw date fields.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mcd_document","commercial_terms":"Public CMS Coverage API slice; no license token or licensed local document content is acquired.","known_gaps":["Local LCD and Article bodies and local code mappings are excluded because those Coverage API endpoints require acceptance of AMA, ADA, and AHA/NUBC license terms.","Public local rows are document indexes, not complete local coverage-policy text.","One optional related-comments endpoint returned HTTP 502 after bounded retries in the accepted snapshot and is recorded as a source limit."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicare_coverage_database","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["document_id"],"backing_store":"glue"},{"source_id":"cms_mcd_document_relationship","source_fqn":"medicare_silver.mcd_document_relationship","title":"CMS Medicare Coverage Database document relationships","domain":"medicare","stage":"silver","status":"live","grain":"One row per (Coverage API snapshot, parent document, public relationship endpoint, publisher row ordinal).","description":"Public relationship records linking national coverage documents to version history, tracking sheets, transmittals, related documents, meetings, assessments, and other publicly exposed coverage artifacts.","identity_key":"parent_document_id","row_count":2965,"last_updated":"2026-07-23","freshness_sla":"Weekly CMS local-data refresh; national updates may occur more frequently.","recollection":{"cadence":"weekly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Join through the explicit parent document type, ID, and version; endpoint plus row ordinal is the physical natural key.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mcd_document_relationship","commercial_terms":"Public CMS Coverage API slice; no license token or licensed local relationship data is acquired.","known_gaps":["Relationships are limited to endpoints explicitly public in the pinned Coverage API v1.6 contract.","Parent and child identities remain source-native strings; do not infer a local policy-to-code relationship from index metadata."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicare_coverage_database","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["parent_document_id"],"backing_store":"glue"},{"source_id":"cms_mcd_document_component","source_fqn":"medicare_silver.mcd_document_component","title":"CMS Medicare Coverage Database public document components","domain":"medicare","stage":"silver","status":"live","grain":"One row per (Coverage API snapshot, parent document, public component endpoint, publisher row ordinal).","description":"Public child components of national coverage artifacts, retaining exact parent identity, endpoint, raw payload, publisher row ordinal, and response-member hash.","identity_key":"parent_document_id","row_count":899,"last_updated":"2026-07-23","freshness_sla":"Weekly CMS local-data refresh; national updates may occur more frequently.","recollection":{"cadence":"weekly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Component rows preserve source-native payloads and must be interpreted in the context of their parent document and endpoint.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mcd_document_component","commercial_terms":"Public CMS Coverage API slice; licensed local LCD and Article component endpoints are excluded.","known_gaps":["No CPT/HCPCS, modifier, ICD-10, bill-type, revenue-code, or SAD component is acquired from a license-token endpoint.","One optional related-comments response is absent under the accepted HTTP 502 source limit."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicare_coverage_database","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["parent_document_id"],"backing_store":"glue"},{"source_id":"cms_mcd_reference","source_fqn":"medicare_silver.mcd_reference","title":"CMS Medicare Coverage Database reference metadata","domain":"medicare","stage":"silver","status":"live","grain":"One row per (Coverage API snapshot, public reference endpoint, publisher row ordinal).","description":"Public Coverage API reference metadata, including states, update periods, local-data schedule, contractor types and subtypes, and contractor records.","identity_key":"record_type","row_count":270,"last_updated":"2026-07-23","freshness_sla":"Weekly CMS local-data refresh.","recollection":{"cadence":"weekly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Endpoint plus publisher row ordinal is the physical natural key; retain raw payload_json when a reference schema changes.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.mcd_reference","commercial_terms":"Public CMS Coverage API reference metadata.","known_gaps":["Reference rows are publisher metadata and do not themselves establish a complete MAC jurisdiction or policy-to-provider join."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicare_coverage_database","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["record_type"],"backing_store":"glue"},{"source_id":"resdac_claim_reference_source_asset","source_fqn":"medicare_silver.resdac_claim_reference_source_asset","title":"ResDAC / CMS claim-reference governed source-asset ledger","domain":"medicare","stage":"silver","status":"live","grain":"One row per governed corpus snapshot and acquired, source-limited, or existing-overlap asset.","description":"Content and rights ledger for four public CMS claim CodeSystems, all 25 recovered CMS Medicare Provider and Supplier Taxonomy Crosswalk revisions, 11 exact NUBC/AMA/ADA source limits, and three pointers to independently mastered Vlada sources.","identity_key":"observed_period,asset_id","row_count":43,"last_updated":"2026-07-24","freshness_sla":"Re-inventory CMS and ResDAC publisher surfaces on each refresh; the taxonomy crosswalk changes only when CMS publishes a revision.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Recollection must preserve publisher authority per asset and fail closed if a governed NUBC/AMA/ADA asset has a payload member.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.resdac_claim_reference_source_asset","commercial_terms":"Public CMS payload only. Externally maintained NUBC code content, AMA CPT descriptions, and ADA CDT descriptions are not acquired or served.","known_gaps":["Eleven NUBC/AMA/ADA families are metadata-only source limits with no payload member and are not claim-code decoders.","Carrier/MAC locality, PSPS, physician provider-service utilization, NUCC taxonomy, and the empirical CPT/revenue modal bridge remain independently mastered sources and are only referenced.","The empirical CPT/revenue modal bridge is not an authoritative NUBC revenue-code decoder.","This source does not supply an AHD-style Medicare/Medicaid/Other net-patient-revenue split."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_claim_reference_code_systems","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"resdac_claim_code","source_fqn":"medicare_silver.resdac_claim_code","title":"CMS public Medicare claim reference codes","domain":"medicare","stage":"silver","status":"live","grain":"One row per immutable CMS FHIR CodeSystem release and source concept ordinal.","description":"Public CMS claim type, near-line record identification, place-of-service, and provider-specialty concepts from four immutable CMS Blue Button CodeSystem assets, with source-native display and definition plus exact release and Bronze lineage.","identity_key":"observed_period,source_asset_id,source_row_number","row_count":382,"last_updated":"2026-07-24","freshness_sla":"Re-inventory the CMS CodeSystem repository on each claim-reference refresh.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Refresh from immutable CMS content and retain source concept ordinals; do not merge externally maintained code sets into this table.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.resdac_claim_code","commercial_terms":"Public CMS CodeSystem content.","known_gaps":["This table covers exactly four CMS-owned code systems and is not a Type of Bill, revenue, discharge, condition, occurrence, value, CPT-description, or CDT-description decoder.","ResDAC documents the variables; the acquired code content is owned and published by CMS.","Preserve code_system and release_date when interpreting a value."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_claim_reference_code_systems","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"resdac_specialty_taxonomy_crosswalk","source_fqn":"medicare_silver.resdac_specialty_taxonomy_crosswalk","title":"CMS Medicare specialty to provider taxonomy crosswalk history","domain":"medicare","stage":"silver","status":"live","grain":"One row per CMS crosswalk release asset and physical source row.","description":"Complete recoverable CMS Medicare Provider and Supplier Taxonomy Crosswalk history across PDF, legacy Socrata CSV, and Data.CMS.gov CSV eras, retaining many-to-many relationships, physical row lineage, raw rows, quality flags, and analytics eligibility.","identity_key":"observed_period,source_asset_id,source_row_number","row_count":12900,"last_updated":"2026-07-24","freshness_sla":"Re-inventory the CMS taxonomy-crosswalk publisher history on each refresh; no annual release is inferred when CMS publishes no revision.","recollection":{"cadence":"event_driven","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve PDF/CSV schema eras, raw rows, source ordinals, and exact revision identity; do not forward-fill sparse legacy rows.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.resdac_specialty_taxonomy_crosswalk","commercial_terms":"Public CMS crosswalk content; NUCC taxonomy content remains an independently mastered source.","known_gaps":["The recoverable publisher history has 25 distinct revisions from 2011-01-20 through 2025-11-01; absent years are not invented releases.","The table is a versioned many-to-many physical crosswalk and must not be collapsed to one taxonomy per Medicare specialty.","Some publisher rows intentionally contain no taxonomy, and malformed legacy values remain noneligible with explicit quality flags.","Join current eligible provider taxonomy codes to the independently mastered NUCC dimension rather than treating this crosswalk as the taxonomy dictionary."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_claim_reference_code_systems","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"x12_claim_reference_source_asset","source_fqn":"medicare_silver.x12_code_list_asset","title":"X12 healthcare code-list source-limit ledger","domain":"medicare","stage":"silver","status":"live","grain":"One row per governed corpus snapshot and X12 healthcare code-list family.","description":"Metadata-only inventory of the 16 X12 healthcare code-list families relevant to claim, remittance, status, payment, adjustment, service, and related transaction semantics, preserving publisher list identity, maintainer, observed release date, source URL, licensing disposition, and the exact no-payload boundary.","identity_key":"observed_period,asset_id","row_count":16,"last_updated":"2026-07-24","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.x12_code_list_asset","notes":null,"superseded_by":null,"tools":[],"dataset_id":"x12_healthcare_code_list_ledger","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ahrq_clinical_reference_source_asset","source_fqn":"medicare_silver.ahrq_source_asset","title":"AHRQ clinical-reference governed source-asset ledger","domain":"medicare","stage":"silver","status":"live","grain":"One row per governed corpus snapshot and publisher asset.","description":"Content and license ledger for the accepted AHRQ CCSR, Quality Indicator SAS, benchmark PDF, and immutable qi-sas repository corpus, preserving exact URLs, files, bytes, hashes, release identity, and current-release status.","identity_key":"observed_period,asset_id","row_count":176,"last_updated":"2026-07-23","freshness_sla":"Annual clinical-code and Quality Indicator releases, with source-surface discovery on refresh.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Recollection must rediscover publisher history, preserve exact content identity, and fail closed at the AMA license gate.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ahrq_source_asset","commercial_terms":"Public AHRQ assets only; the AMA-clickthrough CCS CPT/HCPCS payload is excluded and represented by one metadata-only gated row.","known_gaps":["The AHRQ CCS Services and Procedures CPT/HCPCS payload is not acquired because its publisher gate requires acceptance of third-party AMA terms.","The gated row has no payload URL, file name, byte count, or payload SHA; those nulls are intentional and must not be filled by inference."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_quality_indicators","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ahrq_clinical_reference_ccsr_mapping","source_fqn":"medicare_silver.ahrq_ccsr_mapping","title":"AHRQ CCSR diagnosis and procedure mappings","domain":"medicare","stage":"silver","status":"live","grain":"One row per observed release, source code, CCSR category relationship, and category rank.","description":"Public AHRQ diagnosis and procedure CCS/CCSR history at native multi-category relationship grain, including inpatient/outpatient defaults, source descriptions, category ranks, clinical domains, and row-level lineage.","identity_key":"observed_period,source_asset_id,source_member,source_row_number,relationship_type,category_rank","row_count":5851110,"last_updated":"2026-07-23","freshness_sla":"Annual AHRQ CCSR release, with historical publisher inventory recertified on refresh.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Release version and code system are required for temporal interpretation; observed_period alone is not a clinical-code effective date."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ahrq_ccsr_mapping","known_gaps":["Use release-compatible ICD-10-CM and ICD-10-PCS joins; historical AHRQ releases legitimately retain codes that are retired from a current code dimension.","Multi-category relationships and inpatient/outpatient defaults are distinct rows and must not be collapsed to one category per code."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_ccsr","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":["category_rank","relationship_type","source_member"],"backing_store":"glue"},{"source_id":"ahrq_clinical_reference_ccsr_category","source_fqn":"medicare_silver.ahrq_ccsr_category","title":"AHRQ CCSR category hierarchy","domain":"medicare","stage":"silver","status":"live","grain":"One row per observed release asset, CCSR category, hierarchy level, and clinical domain.","description":"Public AHRQ diagnosis and procedure CCSR category labels and hierarchy relationships, retained by source release and clinical domain with row-level content lineage.","identity_key":"observed_period,source_asset_id,category_code,hierarchy_level,clinical_domain","row_count":13886,"last_updated":"2026-07-23","freshness_sla":"Annual AHRQ CCSR release.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Interpret categories within their code system, release version, schema era, and source asset.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ahrq_ccsr_category","known_gaps":["A category describes a clinical classification and is not a Medicare coverage, payment, or hospital-quality determination.","Parent relationships and hierarchy depth vary by CCSR schema era; retain release version when traversing."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_ccsr","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id"],"unmapped_key_tokens":["category_code","clinical_domain","hierarchy_level"],"backing_store":"glue"},{"source_id":"ahrq_clinical_reference_qi_value_set","source_fqn":"medicare_silver.ahrq_qi_value_set","title":"AHRQ Quality Indicator public SAS value-set rules","domain":"medicare","stage":"silver","status":"live","grain":"One row per observed release, SAS source member, format definition line, and rule ordinal.","description":"Normalized public IQI, PDI, PQI, and PSI SAS VALUE rules across the recoverable publisher history, preserving clinical system, code or range, output, comments, OTHER branches, compact row assignment, and exact Bronze/member/line lineage.","identity_key":"observed_period,source_asset_id,source_member,format_name,source_line_number,rule_ordinal","row_count":10020218,"last_updated":"2026-07-23","freshness_sla":"Annual AHRQ Quality Indicator software release, with historical module inventory recertified on refresh.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Join only analytics-eligible rules to a matching ICD-10-CM, ICD-10-PCS, or MS-DRG dimension and a compatible release period.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ahrq_qi_value_set","commercial_terms":"Public AHRQ Quality Indicator SAS software and Apache-licensed public repository content.","known_gaps":["SAS OTHER branches and administrative/nonclinical formats are retained but are not analytic clinical-code members.","raw_rule_text is the compact assignment fragment at normalized row grain; use source asset, member, and line to recover the complete publisher statement from Bronze.","A value-set membership is methodology logic, not a claim that a hospital has a condition, score, payment, or coverage outcome."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_quality_indicators","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id"],"unmapped_key_tokens":["format_name","rule_ordinal","source_line_number","source_member"],"backing_store":"glue"},{"source_id":"ahrq_clinical_reference_qi_benchmark","source_fqn":"medicare_silver.ahrq_qi_benchmark","title":"AHRQ Quality Indicator national benchmark tables","domain":"medicare","stage":"silver","status":"live","grain":"One row per observed release, source PDF page/table, indicator, group, and row ordinal.","description":"Public IQI, PDI, PQI, and PSI national benchmark and stratified reference tables across modern and legacy layouts, retaining raw metrics, nullable numeric values, suppression/range state, page/table identity, and content lineage.","identity_key":"observed_period,source_asset_id,source_page,table_number,row_ordinal","row_count":7031,"last_updated":"2026-07-23","freshness_sla":"Annual AHRQ Quality Indicator benchmark publication.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve module, release, source page/table, benchmark scope, group, raw values, and suppression state when comparing rows.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ahrq_qi_benchmark","commercial_terms":"Public AHRQ Quality Indicator benchmark publications.","known_gaps":["These are national methodology/reference benchmarks, not CCN-level hospital performance scores.","Suppressed, ranged, and not-applicable publisher values remain nullable and must never be coerced to zero or guessed point values."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_quality_indicators","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id"],"unmapped_key_tokens":["row_ordinal","source_page","table_number"],"backing_store":"glue"},{"source_id":"medpac_databook_source_asset","source_fqn":"medicare_silver.medpac_databook_source_asset","title":"MedPAC annual Data Book source asset inventory","domain":"medicare","stage":"silver","status":"live","grain":"One row per accepted annual full-report PDF or publisher-supplied section workbook.","description":"Complete recoverable public inventory for MedPAC's annual Health Care Spending and the Medicare Program Data Book, covering 24 annual PDFs from 2003 through 2026 and 19 selectively published supporting workbooks from 2024 through 2026, with edition, section, archive/live provenance, document hash, parse disposition, and exact Bronze lineage.","identity_key":"observed_period,asset_id","row_count":43,"last_updated":"2026-07-26","freshness_sla":"Re-inventory the official MedPAC Data Book publication family and supporting workbook surface after each annual release or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate the official annual family, preserve archive/live provenance and exact bytes, and never infer unpublished workbook assets.","watermark_field 'edition_year' is the MedPAC Data Book edition year the asset belongs to; a publication vintage, not a metric measurement period."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medpac_databook_source_asset","commercial_terms":"Public MedPAC policy benchmark publications.","known_gaps":["MedPAC selectively publishes supporting workbooks; absent section workbooks are not fabricated and chart values are not inferred from geometry.","Editions from 2003 through 2019 use immutable Internet Archive captures of original MedPAC files because the current publisher surface does not retain those live downloads.","Topic-specific MedPAC data books are separate publication families and are not silently unioned into this annual core."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"medpac_data_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medpac_databook_page","source_fqn":"medicare_silver.medpac_databook_page","title":"MedPAC annual Data Book page evidence","domain":"medicare","stage":"silver","status":"live","grain":"One physical PDF page per accepted annual edition and source asset.","description":"Layout-preserving page evidence for all 5,091 pages in the 24 accepted annual MedPAC Data Books from 2003 through 2026, retaining page text, section and exhibit detection, page hash, extraction eligibility, source URL, and content-addressed Bronze lineage.","identity_key":"observed_period,asset_id,page_number","row_count":5091,"last_updated":"2026-07-26","freshness_sla":"Parse and certify every page after each accepted annual Data Book release or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Choose edition, section, exhibit, page, population, unit, and measurement period before analysis; retain page-level hashes and eligibility.","watermark_field 'edition_year' is the MedPAC Data Book edition year the page was extracted from; a publication vintage, not the measurement period of any exhibit on the page."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medpac_databook_page","commercial_terms":"Public MedPAC policy benchmark publications.","known_gaps":["The 472 pages without extractable text are retained and explicitly ineligible; text is not invented from chart geometry or image-only content.","Section and exhibit identity support discovery and citation, but edition year is not necessarily the measurement year of every metric shown.","These are national and sector policy benchmarks, not CCN-level hospital facts, claims, cost reports, or rate-setting inputs."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"medpac_data_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medpac_databook_workbook_cell","source_fqn":"medicare_silver.medpac_databook_workbook_cell","title":"MedPAC Data Book supporting workbook cells","domain":"medicare","stage":"silver","status":"live","grain":"One nonempty physical cell per accepted workbook, sheet, and coordinate.","description":"Lossless cell-level evidence from all 19 publisher-supplied MedPAC Data Book supporting workbooks for 2024 through 2026, preserving raw and displayed values, formulas, number formats, merged ranges, hyperlinks, sheet identity, section identity, semantic hashes, and exact Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name,cell_coordinate","row_count":7862,"last_updated":"2026-07-26","freshness_sla":"Acquire and parse every supporting workbook published with each annual Data Book release or correction.","recollection":{"cadence":"annual","watermark_field":"edition_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Select edition, section, workbook, sheet, and exact cell; preserve formula and format semantics and never coerce an unpublished or blank value to zero.","watermark_field 'edition_year' is the MedPAC Data Book edition year the workbook was published with; a publication vintage, not the measurement period of the cell's value."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medpac_databook_workbook_cell","commercial_terms":"Public MedPAC supporting chart-data workbooks.","known_gaps":["Workbook coverage is publisher-selective: six sections in 2024, seven in 2025, and six in 2026; missing section-year workbooks are not inferred.","Blank cells are not rows and must never be interpreted as numeric zero; formulas, formats, merges, and hyperlinks remain source evidence.","Workbook metrics remain exhibit-level national or sector context and must not be assigned to an individual hospital or summed across editions."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"medpac_data_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":["cell_coordinate"],"backing_store":"glue"},{"source_id":"medpac_databook_exhibit","source_fqn":"medicare_silver.medpac_databook_exhibit","title":"MedPAC Data Book workbook exhibit index","domain":"medicare","stage":"silver","status":"live","grain":"One publisher-supplied workbook sheet and exhibit per accepted edition and source asset.","description":"Governed semantic index for all 56 numeric exhibits in the 19 publisher-supplied MedPAC Data Book workbooks for 2024 through 2026, retaining chart or figure identity, exact publisher title and unit, numeric data extent, measurement-year bounds, observation count, source cells, document hash, and Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name","row_count":56,"last_updated":"2026-07-26","freshness_sla":"Rebuild from the accepted content-addressed workbook corpus after each annual Data Book release or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Retain edition year separately from metric measurement period and never widen a national or sector exhibit into a CCN-level fact.","watermark_field 'edition_year' is the MedPAC Data Book edition year the exhibit was published in; a publication vintage carried separately from the exhibit's metric measurement period."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medpac_databook_exhibit","commercial_terms":"Public MedPAC supporting chart-data workbooks.","known_gaps":["This table covers only the publisher-supplied 2024-2026 workbooks; it does not infer exhibits or values from PDF chart geometry.","Workbook files do not carry the annual PDF's full notes and methodology text, so those nullable fields remain unfilled and the page-evidence table remains the citation authority.","Population and geography labels are not guessed from prose; use the exact title, unit, dimensions, and annual PDF page evidence when those scopes matter."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"medpac_data_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"medpac_databook_metric_observation","source_fqn":"medicare_silver.medpac_databook_metric_observation","title":"MedPAC Data Book numeric metric observations","domain":"medicare","stage":"silver","status":"live","grain":"One exact publisher numeric value cell per accepted workbook exhibit, excluding detected period and dimension cells.","description":"Source-faithful numeric observations from every accepted MedPAC supporting workbook, with metric header path, measurement period and year, quarter, unit, category, projection status, exact value/header/dimension cell coordinates, formula, number format, document hash, and content-addressed Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name,value_cell_coordinate","row_count":5567,"last_updated":"2026-07-26","freshness_sla":"Rebuild deterministically from the accepted workbook corpus after each annual Data Book release or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Trace every value through value_cell_coordinate, measure_header_cells_json, dimension_cells_json, document_sha256, and Bronze lineage; do not coerce nulls or infer PDF-only values.","watermark_field 'edition_year' is the MedPAC Data Book edition year the value was published in; a publication vintage, not the measurement period, which is exhibit-specific and carried separately."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.medpac_databook_metric_observation","commercial_terms":"Public MedPAC supporting chart-data workbooks.","known_gaps":["The semantic layer is limited to exact publisher workbook values for 2024-2026; it does not reverse-engineer historical PDF charts or create values for absent workbooks.","Edition year is publication vintage, not measurement year. Always select measurement_period, period_type, unit, metric, and category before comparing editions.","Blank cells are absent, not zero. Publisher numeric zeros, negatives, projections, formulas, formats, and source coordinates are preserved explicitly.","These are national or sector policy observations, not CCN-level hospital facts and not an AHD/AHA payer-revenue split."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"medpac_data_book","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":["value_cell_coordinate"],"backing_store":"glue"},{"source_id":"macpac_macstats_source_asset","source_fqn":"medicare_silver.macpac_macstats_source_asset","title":"MACPAC MACStats source asset inventory","domain":"state","stage":"silver","status":"live","grain":"One row per accepted full-edition PDF, historical Excel container, or exact workbook asset.","description":"Complete public MACStats inventory across 19 official editions from March 2011 through February 2026, retaining 19 full PDFs, 18 historical Excel containers, 456 exact archived workbook members, 43 current workbooks, document hashes, parse disposition, publication vintage, and content-addressed Bronze lineage.","identity_key":"observed_period,asset_id","row_count":536,"last_updated":"2026-07-26","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.macpac_macstats_source_asset","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_macpac_macstats","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"macpac_macstats_page","source_fqn":"medicare_silver.macpac_macstats_page","title":"MACPAC MACStats full-edition page evidence","domain":"state","stage":"silver","status":"live","grain":"One physical PDF page per accepted MACStats edition and full-edition source asset.","description":"Layout-preserving page evidence for all 2,375 pages in the 19 accepted MACStats editions, retaining page text, publisher exhibit detection, page hashes, extraction eligibility, source URL, publication vintage, and exact Bronze lineage.","identity_key":"observed_period,asset_id,page_number","row_count":2375,"last_updated":"2026-07-26","freshness_sla":"Parse and certify every page after each accepted MACStats edition or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_id","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Select edition, exhibit, page, population, unit, and measurement period; retain page-level hashes and extraction eligibility.","watermark_field 'edition_id' is the MACStats edition identifier the page was extracted from; a publication vintage, not the measurement period of any exhibit on the page."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.macpac_macstats_page","commercial_terms":"Public MACPAC Medicaid and CHIP policy benchmark publications.","known_gaps":["The 133 pages without extractable text remain explicit ineligible evidence; text or chart values are not invented from image geometry.","Publisher exhibit detection supports discovery and citation, but publication edition is not necessarily the measurement period of every value shown.","These are state and national Medicaid/CHIP policy pages, not provider-, CCN-, claim-, cost-report-, or hospital-rate-setting facts."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"macpac_macstats","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"macpac_macstats_workbook_cell","source_fqn":"medicare_silver.macpac_macstats_workbook_cell","title":"MACPAC MACStats lossless workbook cells","domain":"state","stage":"silver","status":"live","grain":"One nonempty physical cell per accepted workbook, sheet, and exact coordinate.","description":"Lossless cell-level evidence from all 499 accepted MACStats workbooks across the 19-edition history, preserving raw and displayed values, formulas, formats, merged ranges, hyperlinks, sheet and exhibit identity, document hash, and exact Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name,cell_coordinate","row_count":383797,"last_updated":"2026-07-26","freshness_sla":"Acquire and parse every workbook MACPAC publishes with each edition or correction.","recollection":{"cadence":"annual","watermark_field":"edition_id","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Select edition, workbook, sheet, and exact cell; preserve formula and display semantics and never coerce an absent value to zero.","watermark_field 'edition_id' is the MACStats edition identifier the workbook was published with; a publication vintage, not the measurement period of the cell's value."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.macpac_macstats_workbook_cell","commercial_terms":"Public MACPAC MACStats workbook data.","known_gaps":["Blank cells are absent rather than zero; formulas, formats, merges, hyperlinks, and exact publisher text remain source evidence.","Historical ZIP members retain their container and member lineage; the ZIP container itself is not an additional analytic observation.","Workbook values remain state or national policy evidence and must not be assigned to an individual hospital or summed across editions."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"macpac_macstats","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":["cell_coordinate"],"backing_store":"glue"},{"source_id":"macpac_macstats_exhibit","source_fqn":"medicare_silver.macpac_macstats_exhibit","title":"MACPAC MACStats workbook exhibit index","domain":"state","stage":"silver","status":"live","grain":"One physical workbook sheet per accepted MACStats workbook and edition.","description":"Governed semantic index for 864 physical workbook sheets, retaining canonical versus alternate display role, title, unit, data extent, observation counts, measurement-year bounds, source cells, document hash, publication vintage, and Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name","row_count":864,"last_updated":"2026-07-26","freshness_sla":"Rebuild from the accepted content-addressed workbook corpus after each MACStats edition or correction.","recollection":{"cadence":"annual","watermark_field":"edition_id","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Retain publication edition separately from measurement period and never widen a state or national exhibit into a provider-level fact.","watermark_field 'edition_id' is the MACStats edition identifier the exhibit was published in; a publication vintage carried separately from the exhibit's measurement period."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.macpac_macstats_exhibit","commercial_terms":"Public MACPAC MACStats workbook data.","known_gaps":["All 864 physical sheets remain queryable, but only 676 pass the guarded analytics-eligibility rules; alternate display sheets do not create duplicate analytic authority.","PDF-only exhibits remain page evidence and do not generate inferred workbook exhibits or numeric observations.","Similar exhibit labels across editions are not a universal harmonized metric identity without a separate governed crosswalk."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"macpac_macstats","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"macpac_macstats_metric_observation","source_fqn":"medicare_silver.macpac_macstats_metric_observation","title":"MACPAC MACStats exact metric observations","domain":"state","stage":"silver","status":"live","grain":"One exact canonical workbook value cell when MACPAC publishes a numeric value or an explicit textual value state.","description":"Source-faithful long-form MACStats value states across all accepted canonical workbook sheets, retaining row label and group, merged header path, measurement period, geography when explicit, numeric or textual publisher status, exact value/header/dimension cells, formula, format, document hash, and Bronze lineage.","identity_key":"observed_period,asset_id,sheet_name,value_cell_coordinate","row_count":240074,"last_updated":"2026-07-26","freshness_sla":"Rebuild deterministically from the accepted workbook corpus after each MACStats edition or publisher correction.","recollection":{"cadence":"annual","watermark_field":"edition_id","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Trace every value through value_cell_coordinate, header_cells_json, dimension_cells_json, document_sha256, and Bronze lineage; do not coerce null states or infer PDF-only values.","watermark_field 'edition_id' is the MACStats edition identifier the value was published in; a publication vintage, not the measurement period, which is exhibit-specific and carried separately."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.macpac_macstats_metric_observation","commercial_terms":"Public MACPAC MACStats workbook data.","known_gaps":["Publication edition is not measurement period; compare rows only after binding measurement_period, period_type, unit, metric header, geography, and population.","Blank cells are absent, not zero. Unresolved dashes, not-available values, and dagger states retain null numeric values; only explicit numeric zero or a worksheet-defined quantity-zero symbol is zero.","Only 203,424 of the 240,074 lossless value states have an unambiguous numeric value, header, and measurement period and are analytics-eligible.","Current Exhibit 29 remains measured as of July 1, 2022; it must not be relabeled as 2026 managed-care data.","These are state and national Medicaid/CHIP policy observations, not CCN-level hospital facts and not an AHD/AHA Medicare, Medicaid, and Other net-patient-revenue split."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"macpac_macstats","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":["value_cell_coordinate"],"backing_store":"glue"},{"source_id":"cdc_nhsn_state_hai_progress","source_fqn":"medicare_silver.fact_cdc_nhsn_state_hai","title":"CDC NHSN National and State HAI Progress Data","domain":"state","stage":"silver","status":"live","grain":"One lossless publisher state-data row per reporting year, artifact, source sheet, and source row number; normalized measure and jurisdiction analytics are separately eligibility-gated.","description":"State and territory standardized infection ratios and standardized utilization ratios from CDC NHSN across acute care, critical access, inpatient rehabilitation, and long-term acute-care settings.","identity_key":"reporting_year,publisher_artifact_id,source_sheet,source_row_number","row_count":40792,"last_updated":"2026-08-09","raw_queryable_via":"Athena via medicare_silver.fact_cdc_nhsn_state_hai","notes":null,"superseded_by":null,"tools":[],"dataset_id":"cdc_nhsn_hai_progress","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_row_number"],"unmapped_key_tokens":["publisher_artifact_id","reporting_year","source_sheet"],"backing_store":"glue"},{"source_id":"cms_medicaid_core_set_quality","source_fqn":"medicare_silver.fact_medicaid_core_set_quality","title":"CMS Medicaid/CHIP Child and Adult Core Set State Quality","domain":"medicare","stage":"silver","status":"live","grain":"One publisher row per reporting year, state, reporting program, measure/rate definition, population, and methodology.","description":"State-level performance rates and comparison benchmarks for CMS Medicaid and CHIP Child and Adult Core Set measures, preserving populations, methodologies, suppression statuses, notes, state comments, and source lineage.","identity_key":"reporting_year,state_code,reporting_program,measure_abbreviation,rate_definition,population,methodology","row_count":31344,"last_updated":"2026-08-08","raw_queryable_via":"Athena (read-only): medicare_silver.fact_medicaid_core_set_quality","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_cms_medicaid","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state_code"]},"technical_keys":[],"unmapped_key_tokens":["measure_abbreviation","methodology","population","rate_definition","reporting_program","reporting_year"],"backing_store":"glue"},{"source_id":"cms_medicaid_health_home_quality","source_fqn":"medicare_silver.fact_medicaid_health_home_quality","title":"CMS Medicaid Health Home Program Quality","domain":"state","stage":"silver","status":"live","grain":"One physical publisher observation cell per reporting year, measure, state, approved Health Home program, population, methodology, and denominator/rate stratum.","description":"Lossless CMS Medicaid Health Home measure-performance tables for 2019-2024, preserving program identity, measure-specific column headers, raw table context, suppression statuses, and exact ZIP/PDF lineage.","identity_key":"reporting_year,source_member,source_page,source_table_ordinal,source_row_ordinal,source_column_ordinal","row_count":12979,"last_updated":"2026-08-09","raw_queryable_via":"Athena (read-only): medicare_silver.fact_medicaid_health_home_quality","notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicaid_health_home_quality","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["reporting_year","source_column_ordinal","source_member","source_page","source_row_ordinal","source_table_ordinal"],"backing_store":"glue"},{"source_id":"cms_medicaid_chip_enrollment_source_asset","source_fqn":"medicare_silver.cms_medicaid_chip_enrollment_source_asset","title":"CMS Medicaid and CHIP monthly-enrollment source asset inventory","domain":"state","stage":"silver","status":"live","grain":"One row per governed current portal asset, official historical report PDF or ZIP container, or exact expanded archive member.","description":"Complete physical source inventory for the accepted monthly state Medicaid and CHIP applications, eligibility, and enrollment family, retaining the current CSV and metadata, the official report-history page, 80 historical PDFs, 48 ZIP containers, 48 workbook members, 24 retained PDF members, document hashes, parse disposition, and content-addressed Bronze lineage.","identity_key":"observed_period,asset_id","row_count":204,"last_updated":"2026-07-26","freshness_sla":"Re-inventory the Data.Medicaid.gov dataset and official CMS report-history surface after every monthly release or publisher correction.","recollection":{"cadence":"monthly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate both official publisher surfaces, preserve container/member lineage, and do not treat the July-September 2013 baseline as ordinary September activity.","watermark_field corrected 2026-09-04 to 'observed_period', the M-2 period column on this asset-inventory table (the previously declared 'reporting_period' is not one of its columns, per the 2026-09-01 columns snapshot); reporting_period lives on the monthly state fact, not on the asset rows."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cms_medicaid_chip_enrollment_source_asset","commercial_terms":"Public CMS Medicaid and CHIP enrollment publications.","known_gaps":["The standardized portal rows cover the July-September 2013 baseline and June 2017 through March 2026; older report-era workbooks are retained losslessly but not silently conformed.","ZIP containers and their exact members are separate physical lineage assets, not additional enrollment observations.","Historical PDF chart values are not inferred from page geometry."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicaid_chip_enrollment_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_medicaid_chip_enrollment_workbook_cell","source_fqn":"medicare_silver.cms_medicaid_chip_enrollment_workbook_cell","title":"CMS Medicaid and CHIP historical report workbook cells","domain":"state","stage":"silver","status":"live","grain":"One nonempty physical cell per accepted historical report workbook, sheet, and exact coordinate.","description":"Lossless cell-level evidence from all 48 official historical report workbooks, preserving raw and displayed values, formulas, formats, merged ranges, hyperlinks, exact ZIP container/member lineage, document hash, and content-addressed Bronze provenance.","identity_key":"observed_period,asset_id,sheet_name,cell_coordinate","row_count":158175,"last_updated":"2026-07-26","freshness_sla":"Rebuild from the exact accepted report-history bundle whenever CMS changes a historical archive or publishes another workbook.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Select the exact asset, sheet, and coordinate; preserve formula/display semantics and never coerce absent cells to zero.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cms_medicaid_chip_enrollment_workbook_cell","commercial_terms":"Public CMS Medicaid and CHIP historical report workbooks.","known_gaps":["This is source-era evidence, not a harmonized pre-2017 monthly fact table; workbook layouts and labels remain as published.","Blank cells are absent rather than zero, and PDF-only values are not synthesized.","Cell rows must not be summed across reports, sheets, or source eras without an independently governed mapping."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicaid_chip_enrollment_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name"],"unmapped_key_tokens":["cell_coordinate"],"backing_store":"glue"},{"source_id":"cms_medicaid_chip_enrollment_monthly_state","source_fqn":"medicare_silver.cms_medicaid_chip_enrollment_monthly_state","title":"CMS monthly state Medicaid and CHIP enrollment operations","domain":"state","stage":"silver","status":"live","grain":"One state or District of Columbia row per reporting period and publisher preliminary or updated/final revision.","description":"Source-faithful monthly state applications, eligibility determinations, enrollment, application-processing, and call-center measures from the current CMS portal distribution, retaining preliminary and updated revisions, final-report status, exact metric footnotes, latest-revision flags, semantic row hashes, and Bronze lineage.","identity_key":"observed_period,state_abbreviation,report_revision,final_report","row_count":10812,"last_updated":"2026-07-26","freshness_sla":"Refresh after each monthly Data.Medicaid.gov release and preserve both preliminary and updated publisher revisions.","recollection":{"cadence":"monthly","watermark_field":"reporting_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Bind revision and final-report status, select latest revision intentionally, retain footnotes, and never relabel the 201309 baseline as a normal month.","watermark_field 'reporting_period' is the publisher's monthly reporting period the row's counts describe (the 201309 baseline is such a period); a later publisher revision of the same period is a separate row distinguished by report_revision and final_report, so select the revision intentionally."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cms_medicaid_chip_enrollment_monthly_state","commercial_terms":"Public CMS Medicaid and CHIP applications, eligibility, and enrollment data.","known_gaps":["For current analysis select is_latest_revision=true; preliminary rows coexist with updated/final rows and must not be summed.","Reporting period 201309 is the publisher's July-September 2013 average baseline, not ordinary September-only activity.","Blank numeric values are null, not zero, and each metric's exact footnote must remain in scope.","The standardized series has no portal rows for October 2013 through May 2017; historical workbooks remain separate lossless evidence rather than fabricated conformed facts."],"notes":null,"superseded_by":null,"tools":["get_medicaid_mco_enrollment"],"dataset_id":"cms_medicaid_chip_enrollment_reports","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["final_report","report_revision","state_abbreviation"],"backing_store":"glue"},{"source_id":"cms_medicaid_managed_care_plan_source_asset","source_fqn":"medicare_silver.cms_medicaid_managed_care_plan_source_asset","title":"CMS Medicaid managed-care plan-enrollment source inventory","domain":"state","stage":"silver","status":"live","grain":"One row per accepted publisher history page, dataset metadata asset, or exact consolidated CSV.","description":"Governed source ledger for CMS Medicaid managed-care enrollment by program and plan, retaining the official history page, Data.Medicaid.gov metadata, exact 2016-2024 consolidated CSV, publisher bytes and document hashes, parse disposition, and content-addressed Bronze lineage.","identity_key":"observed_period,asset_id","row_count":3,"last_updated":"2026-07-26","freshness_sla":"Re-inventory the official enrollment-report and Data.Medicaid.gov surfaces after every annual release or publisher correction.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate both publisher surfaces, retain the exact consolidated CSV, and do not treat labels as stable plan IDs.","watermark_field corrected 2026-09-04 to 'observed_period', the M-2 period column on this asset-inventory table (the previously declared 'calendar_year' is not one of its columns, per the 2026-09-01 columns snapshot); calendar_year lives on the plan-enrollment fact, not on the asset rows."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cms_medicaid_managed_care_plan_source_asset","commercial_terms":"Public CMS Medicaid managed-care enrollment publications.","known_gaps":["The accepted consolidated source spans calendar years 2016-2024; no earlier plan-level rows are published in this dataset.","This inventory is separate from the four-state T-MSIS county/MCO/service-category utilization product.","Plan labels and parent organizations are publisher text, not stable payer identities."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_medicaid_managed_care_enrollment_report","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_medicaid_managed_care_plan_enrollment","source_fqn":"medicare_silver.cms_medicaid_managed_care_plan_enrollment","title":"CMS Medicaid managed-care enrollment by program and plan","domain":"state","stage":"silver","status":"live","grain":"One physical publisher row per calendar year, state, program, plan label, and reported geographic region.","description":"Annual Medicaid managed-care enrollment for 2016-2024 with raw and normalized state labels, program and plan names, geographic region, separate Medicaid-only, dual, and total counts, exact raw values and value-status semantics, parent organization, stable physical source-row identity, semantic row hash, and Bronze lineage.","identity_key":"calendar_year,source_row_number","row_count":7804,"last_updated":"2026-07-26","freshness_sla":"Replace complete publisher calendar-year partitions after each accepted annual release or correction.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve raw values and value_status, do not recompute totals, retain publisher duplicate rows, and join plan labels only through a separately governed measured crosswalk.","watermark_field 'calendar_year' is the publisher calendar year the row was published for; a complete publisher calendar-year partition is replaced on each accepted annual release or correction."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cms_medicaid_managed_care_plan_enrollment","commercial_terms":"Public CMS Medicaid managed-care enrollment data.","known_gaps":["CMS states that published 0 may mean an exact zero or confidentiality suppression below ten; reported_zero_or_suppressed must never be asserted as exact zero.","Medicaid-only, dual, and total fields remain separate. Seven publisher rows do not arithmetically reconcile and totals must not be recomputed.","Four duplicated label combinations are retained as eight distinct source rows; source_row_number, not the label tuple, is the certified identity.","Plan names and parent organizations are not stable identifiers and no fuzzy payer crosswalk is implied.","This annual point-in-time plan roster is not claims, county service utilization, HCRIS, or an AHD/AHA payer-revenue split."],"notes":null,"superseded_by":null,"tools":["get_medicaid_mco_enrollment"],"dataset_id":"cms_medicaid_managed_care_enrollment_report","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_row_number"],"unmapped_key_tokens":["calendar_year"],"backing_store":"glue"},{"source_id":"ca_medi_cal_managed_care_enrollment","source_fqn":"medicare_silver.fact_ca_medi_cal_managed_care_enrollment","title":"California DHCS Medi-Cal managed-care enrollment","domain":"state","stage":"silver","status":"live","grain":"One physical publisher row per enrollment month and source row number.","description":"Lossless cumulative monthly California Medi-Cal managed-care enrollment by publisher plan-type label, county, and plan label from January 2007 through June 2026, preserving raw and normalized labels, reported or suppressed count state, annotations, unexplained publisher-key duplicates, semantic row hash, and content-addressed Bronze lineage.","identity_key":"enrollment_month,source_row_number","row_count":31178,"last_updated":"2026-07-31","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ca_medi_cal_managed_care_enrollment","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_row_number"],"unmapped_key_tokens":["enrollment_month"],"backing_store":"glue"},{"source_id":"national_medicaid_mco_enrollment_tracker_reported_observation_v2","source_fqn":"medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v2","title":"National Medicaid MCO enrollment ledger - every state's reported plan enrollment observations, one view","domain":"state","stage":"semantic_view","status":"partial","grain":"One source-native reported enrollment observation from one of 64 state adapter tables; (source_table_fqn, source_observation_key) is unique (measured 2026-09-24, 1,517,497 rows = 1,517,497 distinct keys, Athena eb762e94).","description":"A ledger, not a total. The union of every structured state Medicaid managed-care enrollment observation Vlada holds: 45 jurisdictions (44 states and DC plus Puerto Rico), 64 medicare_silver state tables, observation periods January 2000 to August 2026. Each row keeps the publisher's own cadence, measure name, unit, time basis, program, geography and plan label, its value status (reported, zero, suppressed, missing), its row role (detail component, publisher control, overlapping summary) and its file lineage. Plan and parent identities are the publisher's text; no canonical crosswalk is applied.","identity_key":"source_table_fqn,source_observation_key","row_count":1517497,"last_updated":"2026-08-31","raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v2","notes":"Registered 2026-09-24 (Data Tracker states program, lane B) as register source w8 vlada_w8_national_medicaid_mco_enrollment_ledger. status is partial because coverage is incomplete (16 jurisdictions without monthly plan rows, 7 absent) and no row is authorized for aggregation, so every raw read carries the status caveat. The 64 underlying state tables stay uncatalogued: the view is the only door, and the guard parses only the table the SQL names.","superseded_by":null,"tools":[],"dataset_id":"vlada_w8_national_medicaid_mco_enrollment_ledger","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["source_observation_key","source_table_fqn"],"backing_store":"glue"},{"source_id":"ca_calaim_1915b_source_occurrence","source_fqn":"medicare_silver.ca_calaim_1915b_source_occurrence","title":"California CalAIM 1915(b) official source occurrences","domain":"state","stage":"silver","status":"live","grain":"One row per frozen corpus snapshot and official DHCS source occurrence, including acquired aliases, proposed non-operative material, and exact source-limit occurrences.","description":"Production-reconciled and exact-replay-idempotent lossless occurrence ledger for the CalAIM CA-0017.R10 authority chain. It preserves source-native role and authority status; distinct publisher, submission, approval, waiver-effective, implementation, table-as-of, and acquisition dates; official and acquisition URLs; exact content identity; alias ordinals; proposal and acquisition flags; raw manifest JSON; and Bronze lineage without inferring an operative program roster.","identity_key":"corpus_snapshot_date,occurrence_id","row_count":27,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS or CMS publishes a new submission, approval, technical correction, renewal item, or correction to the official index.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate the official DHCS indexes, pin exact bytes and source limits, retain proposal status and every independent date axis, and never select current authority from artifact date alone.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_calaim_1915b_source_occurrence","commercial_terms":"Public California DHCS and CMS waiver-authority documents.","known_gaps":["Production contains 27 reconciled occurrence rows at Iceberg snapshot 5933192372329332196; exact-bundle replay returned IDEMPOTENT_SKIP and preserved this snapshot. Hosted MCP data proof remains a separate post-merge rung.","The R10.02 MCMC/Dental MC cost-effectiveness workbook occurrence `appr2024_ce_mcmc` is an exact source-limit sentinel: `is_acquired=false`, payload/hash fields remain null, and `source_limit_reason` remains populated; it must not disappear or acquire invented bytes.","The 2026 renewal summary and tribal notice occurrences are `proposed_nonoperative`; proposal appearance is not operative federal authority and these rows must never enter an operative-current selection.","`authority_status`, source role, and the separate date axes must be filtered explicitly. A newer artifact date does not supersede section-level inherited language or an embedded older table-as-of date.","This source establishes document evidence for one CalAIM 1915(b) chain, not observed enrollment, executed contracts, provider networks, capitation rates, paid claims, or a complete California authority roster.","The R09-and-earlier SMHS 1915(b) chain is a separate required source; completing this table does not close `program_delivery_roster` or `spa_waiver_authority`."],"notes":"Production schema columns are corpus_snapshot_date, occurrence_id, action_id, role, authority_status, artifact_date, publisher_occurrence_date, state_submission_date, cms_approval_date, waiver_effective_start/end, provision_implementation_start/end, table_as_of_date, effective_text, file_type, publisher_filename, official_url, acquisition_url, byte_count, document_sha256, expected_page_count, parse_disposition, source_limit_reason, content_occurrence_count/ordinal, is_content_alias, is_proposed_nonoperative, is_acquired, manifest_sha256, raw_occurrence_json, semantic_row_sha256, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_calaim_1915b_waiver_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date","occurrence_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_calaim_1915b_pdf_page","source_fqn":"medicare_silver.ca_calaim_1915b_pdf_page","title":"California CalAIM 1915(b) physical PDF-page evidence","domain":"state","stage":"silver","status":"live","grain":"One physical PDF page per exact document SHA-256 and one-based page number, with content-identical publisher occurrences represented once and linked through a canonical occurrence.","description":"Production-reconciled and exact-replay-idempotent lossless page layer for acquired CalAIM 1915(b) PDFs, preserving layout-aware extracted text, page-text hash, word count, extraction method, quality flags, exact document identity, content-alias count, semantic-row hash, and Bronze lineage. It is citation evidence, not an operative-rule or structured program fact table.","identity_key":"document_sha256,page_number","row_count":2839,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each accepted CalAIM 1915(b) corpus update or exact-byte publisher correction.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reparse only exact accepted PDF bytes, retain page and text hashes, treat analytics eligibility as extraction fitness rather than authority, and resolve proposed status through the occurrence ledger.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_calaim_1915b_pdf_page","commercial_terms":"Public California DHCS and CMS waiver-authority documents.","known_gaps":["Production contains 2,839 reconciled physical-page rows at Iceberg snapshot 8750292831544832998; exact-bundle replay returned IDEMPOTENT_SKIP and preserved this snapshot. Hosted MCP data proof remains a separate post-merge rung.","Extraction retained 2,783 `pypdf_layout` pages and 56 `pypdf_plain_rotated_fallback` pages; 10 pages retain the `empty_extracted_text` quality flag rather than invented text.","`is_analytics_eligible` describes extraction fitness only; it is not legal operativity. Join `canonical_occurrence_id` to the occurrence ledger and exclude `is_proposed_nonoperative=true` before any operative-authority use.","Content-identical aliases are deduplicated by exact SHA-256 at the page layer. The canonical occurrence is lineage, not permission to discard the other official roles or URLs from the occurrence ledger.","Empty extracted text remains a quality flag and must not be filled, OCR-invented, or interpreted as an absent legal provision without separately accepted OCR evidence.","Page text preserves source evidence but does not resolve inherited provisions, redline semantics, table-as-of dates, or provision-level implementation periods."],"notes":"Production schema columns are corpus_snapshot_date, document_sha256, canonical_occurrence_id, content_occurrence_count, page_number, page_text, page_text_sha256, word_count, extraction_method, semantic_row_sha256, quality_flags, is_analytics_eligible, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_calaim_1915b_waiver_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_calaim_1915b_workbook_cell","source_fqn":"medicare_silver.ca_calaim_1915b_workbook_cell","title":"California CalAIM 1915(b) physical workbook-cell evidence","domain":"state","stage":"silver","status":"live","grain":"One nonempty physical cell per exact workbook SHA-256, physical sheet name, and cell coordinate.","description":"Production-reconciled and exact-replay-idempotent lossless cell layer for acquired CalAIM 1915(b) cost-effectiveness workbooks, preserving raw and displayed values, formulas, data type, number format, style array, merged range, hyperlink, comment, semantic text, quality flags, exact workbook identity, content-alias count, semantic-row hash, and Bronze lineage without converting projections into actual claims or revenue.","identity_key":"document_sha256,sheet_name,cell_coordinate","row_count":19941,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each accepted CalAIM 1915(b) workbook publication, approval package, or exact-byte correction.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reparse only exact accepted XLSX bytes, preserve formula/display/style/merge semantics, keep blanks absent rather than zero, and reconcile missing workbooks to occurrence-level source limits.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_calaim_1915b_workbook_cell","commercial_terms":"Public California DHCS and CMS waiver cost-effectiveness workbooks.","known_gaps":["Production contains 19,941 reconciled nonempty-cell rows at Iceberg snapshot 4466256569331871445; exact-bundle replay returned IDEMPOTENT_SKIP and preserved this snapshot. Hosted MCP data proof remains a separate post-merge rung.","Three acquired workbooks contain 28 physical sheets; 27 sheets emit nonempty cell rows. A physical sheet with no emitted rows is absence of nonempty cells, not a zero-valued observation.","Blank cells are absent, not zero, false, excluded, or not applicable. Formula, displayed value, raw value, style, merge, hyperlink, and comment state must remain distinct.","Cost-effectiveness workbook values are projections and federal tests unless the source explicitly says otherwise; they are not paid claims, plan revenue, capitation rates, or observed enrollment.","`is_analytics_eligible` is extraction fitness, not legal operativity. Authority status and source role come from the occurrence ledger and must remain in scope.","The unresolved `appr2024_ce_mcmc` source-limit occurrence must produce no cell rows unless exact official bytes are later acquired and separately accepted; absence here must reconcile to the occurrence-ledger sentinel rather than being hidden."],"notes":"Production schema columns are corpus_snapshot_date, document_sha256, canonical_occurrence_id, content_occurrence_count, sheet_name/index, cell_coordinate, row_number, column_number, raw_value_json, displayed_value_json, formula, data_type, number_format, style_id, style_array_json, merged_range, hyperlink_json, comment_json, semantic_value_text, semantic_row_sha256, quality_flags, is_analytics_eligible, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_calaim_1915b_waiver_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256","sheet_name"],"unmapped_key_tokens":["cell_coordinate"],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_contract_source_occurrence","source_fqn":"medicare_silver.ca_medi_cal_managed_care_contract_source_occurrence","title":"California Medi-Cal managed-care contract source occurrences","domain":"state","stage":"silver","status":"live","grain":"One frozen corpus snapshot and official DHCS contract-publication occurrence, including acquired payloads and exact retrieval limits.","description":"Production-reconciled and exact-replay-idempotent occurrence ledger for California physical-health Medi-Cal managed-care boilerplates, publisher-labeled amendment/full-restatement packages, Exhibit L variants, and explicitly nonoperative drafts. It preserves artifact class, source-native dates, exact payload identity, acquisition/source-limit state, content aliases, operativity and fact-eligibility flags, semantic hashes, and M-2 lineage without manufacturing executed contract, amendment, CMS-review, or rate facts.","identity_key":"corpus_snapshot_date,occurrence_id","row_count":31,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS publishes, replaces, or recovers a managed-care boilerplate, amendment/restatement package, Exhibit L artifact, or contract-related draft.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate exact DHCS publication surfaces and recover raw bytes before adding rows; preserve source limits and independent date axes; never infer execution, CMS approval, chronology, or rates from labels, metadata, variants, blanks, or publisher assertions.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_managed_care_contract_source_occurrence","commercial_terms":"Public California Department of Health Care Services managed-care contract publications.","known_gaps":["Production contains 31 reconciled occurrences at Iceberg snapshot 9087821636864459865: 14 acquired PDFs and 17 exact source-limit occurrences. Query `6dec6f84-0d08-4988-bcf4-8bf9651acb84` proves zero duplicate certified keys, zero required-lineage nulls, zero source-limit payload-field violations, and zero signed base/amendment or rate facts; exact replay returned four `IDEMPOTENT_SKIP` results and preserved all four snapshots.","Fourteen current boilerplate, Two-Plan, crosswalk, and Exhibit L occurrences plus three draft/APL occurrences remain blocked or unrecovered; null bytes, hashes, and pages are source limits, not zero.","Exhibit L variants 1-10 are content variants, not chronology. Drafts are explicitly nonoperative, and publisher-labeled restatements are not executed plan amendments.","The source does not prove signed plan-specific contracts, executed amendments, contract terms, CMS review, contractor identity, clause facts, rates, networks, enrollment, claims, or waiver authority."],"notes":"Production schema preserves artifact class, managed-care models, raw publisher labels and dates, acquisition/source-limit evidence, content aliases, explicit operativity, Exhibit L non-temporal semantics, fact-eligibility sentinels, raw JSON, semantic hash, and M-2 lineage. Query promotion and certification are proven; hosted MCP data proof, customer-live status, terminal completion, and family completion remain gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_contracts","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date","occurrence_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_contract_index_snapshot","source_fqn":"medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot","title":"California Medi-Cal managed-care contract index snapshots","domain":"state","stage":"silver","status":"live","grain":"One frozen corpus snapshot and exact archived official DHCS index occurrence.","description":"Lossless archived-index ledger for four exact DHCS managed-care boilerplate publication states. It preserves official and acquisition URLs, archive capture, exact bytes and hashes, linked and unresolved corpus identities, publisher notes, content aliases, semantic hashes, and M-2 lineage. Index rows prove publisher occurrence and link history, not contracts or amendments.","identity_key":"corpus_snapshot_date,snapshot_id","row_count":4,"last_updated":"2026-08-01","freshness_sla":"Event-driven when a distinct official index state is recovered and separately accepted.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Recover and hash exact index bytes, preserve capture and publisher dates separately, retain unresolved links, and never treat index text as executed contract evidence.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot","commercial_terms":"Public California Department of Health Care Services managed-care contract publication indexes.","known_gaps":["Production contains four reconciled archived-index occurrences totaling 264,414 bytes at Iceberg snapshot 3889930429454777084, with zero duplicate certified keys, zero required-lineage nulls, and zero contract-fact-eligible rows under query `6dec6f84-0d08-4988-bcf4-8bf9651acb84`.","The 2024 index displayed an approved/pending disclaimer but no additional amendment link inventory; absence from an index snapshot is not proof that no contract or amendment existed."],"notes":"Index snapshots are publisher-occurrence evidence only. Exact replay returned `IDEMPOTENT_SKIP` and preserved the snapshot; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_contracts","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date"],"unmapped_key_tokens":["snapshot_id"],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_contract_index_snapshot_text","source_fqn":"medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot_text","title":"California Medi-Cal managed-care contract index text","domain":"state","stage":"silver","status":"live","grain":"One exact archived-index document SHA-256 and decoded lossless text document.","description":"Decoded text layer for four exact DHCS archived contract-publication indexes, preserving canonical snapshot identity, content aliases, text hash, byte and character counts, decoding/extraction method, quality flags, semantic hash, and M-2 lineage. It supports publisher-link research but emits no contract facts.","identity_key":"document_sha256","row_count":4,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each separately accepted exact index payload or decoding correction.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Decode only accepted exact index bytes, retain text hashes and quality state, and resolve legal meaning through acquired document evidence rather than labels alone.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_managed_care_contract_index_snapshot_text","commercial_terms":"Public California Department of Health Care Services managed-care contract publication indexes.","known_gaps":["Production contains four reconciled decoded-index documents at Iceberg snapshot 2348662581506271121, with zero duplicate certified keys, zero required-lineage or text-hash nulls, and zero contract-fact-eligible rows under query `6dec6f84-0d08-4988-bcf4-8bf9651acb84`.","Decoded index language and link labels are discovery evidence; they are not signatures, execution dates, contract terms, or CMS approval."],"notes":"Exact replay returned `IDEMPOTENT_SKIP` and preserved the snapshot. Query promotion and certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_contracts","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_contract_pdf_page","source_fqn":"medicare_silver.ca_medi_cal_managed_care_contract_pdf_page","title":"California Medi-Cal managed-care contract PDF-page evidence","domain":"state","stage":"silver","status":"live","grain":"One exact acquired PDF document SHA-256 and one-based physical page number.","description":"Lossless physical-page layer for 14 acquired DHCS managed-care boilerplate and publisher-labeled restatement PDFs. It preserves document/page hashes, canonical occurrence identity, layout-aware text, extraction quality, fact-eligibility sentinels, semantic hashes, and M-2 lineage. It is citation evidence and contains no executed contract, plan-specific amendment, or rate facts.","identity_key":"document_sha256,page_number","row_count":3822,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each separately accepted exact contract-publication PDF recovery or extraction correction.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reparse only accepted exact PDF bytes, preserve page/text hashes and quality flags, emit no pages for source limits, and never infer execution, CMS approval, rates, or contract terms from page text alone.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_managed_care_contract_pdf_page","commercial_terms":"Public California Department of Health Care Services managed-care contract publications.","known_gaps":["Production contains 3,822 reconciled physical pages at Iceberg snapshot 1127959268214226546. Query `6dec6f84-0d08-4988-bcf4-8bf9651acb84` proves zero duplicate certified keys, zero required-lineage/page-hash nulls, and zero executed-contract, plan-specific-amendment, or rate-fact rows.","The 17 source-limit occurrences correctly emit no physical pages. Their absence is not evidence of a zero-page document or absent contract.","Page text from a boilerplate or publisher-labeled full restatement is not signed plan-specific execution evidence; legal classification must retain the occurrence-ledger artifact class and eligibility flags."],"notes":"Exact replay returned `IDEMPOTENT_SKIP` and preserved the snapshot. Query promotion and certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_contracts","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_roster_source_occurrence","source_fqn":"medicare_silver.ca_medi_cal_mcp_roster_source_occurrence","title":"California Medi-Cal managed-care roster source occurrences","domain":"state","stage":"silver","status":"live","grain":"One frozen corpus snapshot and official DHCS managed-care roster source occurrence, including acquired artifacts and explicit retrieval limits.","description":"Production-reconciled and exact-replay-idempotent occurrence ledger for California physical-health Medi-Cal managed-care program-delivery roster evidence. It preserves source roles, dates, exact payload identity, content aliases, acquisition state, directory evidence flags, proposal/operativity eligibility, source limits, raw occurrence JSON, semantic hashes, and M-2 lineage without treating directory listings as contract, enrollment, network, rate, or federal-authority proof.","identity_key":"corpus_snapshot_date,occurrence_id","row_count":15,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS publishes or changes a managed-care map, county-plan matrix, transition guide, or beneficiary directory.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate official DHCS surfaces, pin exact bytes, retain source limits and all independent date/status axes, and never infer operativity from publication or archive dates.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_mcp_roster_source_occurrence","known_gaps":["Production contains 15 reconciled occurrences at Iceberg snapshot 3757758753004643270: nine acquired PDFs and six explicit source-limit occurrences. Validation query `bc7588bd-b2cc-4183-97ec-ca1c61c53fa6` proves zero duplicate certified-key groups and zero required-lineage null rows; exact replay returned three `IDEMPOTENT_SKIP` results and preserved all three snapshots. Hosted MCP data proof remains a separate post-merge rung.","Current map and 59-page beneficiary directory raw acquisition remain blocked by Incapsula; bytes, hashes, and derived physical rows are absent rather than invented.","Transition-guide versions 1, 3, 4, and 6 remain unrecovered; one archive response is truncated and rejected as a valid PDF.","This occurrence ledger does not prove observed enrollment, executed contracts, provider networks, rates, paid claims, or federal waiver authority."],"notes":"Production schema preserves all source-native date strings, official/acquisition URLs, exact byte and document hashes, parse/source-limit evidence, proposed/directory/operativity eligibility flags, content-alias fields, raw JSON and M-2 lineage. The accepted bundle has exactly one Bronze object version. Query promotion and source certification are proven; hosted MCP data proof, customer-live status, terminal completion, and family completion remain gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_program_delivery_roster","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date","occurrence_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_roster_pdf_page","source_fqn":"medicare_silver.ca_medi_cal_mcp_roster_pdf_page","title":"California Medi-Cal managed-care roster PDF-page evidence","domain":"state","stage":"silver","status":"live","grain":"One exact acquired PDF document SHA-256 and one-based physical page number.","description":"Production-reconciled and exact-replay-idempotent lossless page layer for acquired California Medi-Cal managed-care roster PDFs, preserving exact document and page-text hashes, layout-aware text, extraction method and quality flags, canonical occurrence linkage, proposal status, extraction fitness, semantic hashes, and M-2 lineage. It is citation evidence, not a plan-operativity or contract table.","identity_key":"document_sha256,page_number","row_count":515,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each separately accepted exact-byte roster-document recovery or correction.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reparse only accepted exact PDF bytes; retain page/text hashes and quality flags; never create pages for unresolved occurrences or infer program facts from page eligibility.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_mcp_roster_pdf_page","known_gaps":["Production contains 515 reconciled physical-page rows at Iceberg snapshot 5935795655934060980. Validation query `bc7588bd-b2cc-4183-97ec-ca1c61c53fa6` proves zero duplicate certified-key groups and zero required-lineage null rows; exact replay returned `IDEMPOTENT_SKIP` and preserved the snapshot. Hosted MCP data proof remains a separate post-merge rung.","Source-limit occurrences emit no physical page rows; their absence must reconcile to the occurrence ledger and is not evidence of a zero-page document.","Page extraction eligibility is extraction fitness only. Legal or program operativity must be resolved through the occurrence and structured roster layers."],"notes":"Production schema preserves canonical occurrence identity, content-occurrence count, physical page text and hashes, word counts, extraction methods, quality flags, roster/proposal status, analytics eligibility, semantic hashes and M-2 lineage. Query promotion and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_program_delivery_roster","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_medi_cal_mcp_county_plan_roster","source_fqn":"medicare_silver.ca_medi_cal_mcp_county_plan_roster","title":"California Medi-Cal county-plan program-delivery roster","domain":"state","stage":"silver","status":"live","grain":"One source roster occurrence, roster year, county name, and source-native plan ordinal.","description":"Production-reconciled and exact-replay-idempotent structured transcription of the final DHCS 2023-to-2024 county-plan/model matrix. It retains raw display and legal names, source-native model and plan ordering, plan class, prime/subcontracted status, eligibility qualifier, notes and footnotes, exact citation, and separate operative/current/analytics flags. It includes the source-native Medi-Cal Fee For Service delivery row and does not coerce it into a managed-care plan.","identity_key":"occurrence_id,roster_year,county_name,plan_ordinal","row_count":218,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS publishes a newly accepted county-plan matrix or explicit approval evidence changes row eligibility.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve source-native plan rows and names, select operativity and analytics flags explicitly, retain the FFS row as non-plan evidence, and never infer approval, enrollment, contract, network, rate, or authority status.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_medi_cal_mcp_county_plan_roster","known_gaps":["Production contains 218 reconciled rows at Iceberg snapshot 8963835898133945471: 104 for 2023 and 114 for 2024. Query `bc7588bd-b2cc-4183-97ec-ca1c61c53fa6` proves zero duplicate certified-key groups, zero required-lineage null rows, 186 operative rows, 185 analytics-eligible rows, and 32 Kaiser 2024 rows; corrected query `662a9cc1-2433-4114-b923-3caea6d6089d` proves exactly one retained Fee For Service row.","All 32 Kaiser 2024 rows were marked pending federal approval in this artifact and remain non-operative and analytics-ineligible absent separately accepted approval evidence.","The one Medi-Cal Fee For Service row is source-native delivery evidence, not a managed-care plan; operative count and analytics-eligible count therefore differ by one.","Raw plan names remain source faithful, including distinct `Health Plan San Joaquin` and `Health Plan of San Joaquin` variants and ten capitalization/punctuation cases. No fuzzy identity merge has been applied.","This matrix is not observed enrollment, an executed contract, a provider network, a rate, a paid claim, or federal waiver authority, and it does not complete California's program-delivery-roster family."],"notes":"Production schema preserves roster year/status and dates; county and raw/normalized program model; source-native ordinal; raw display/legal names, notes and footnotes; plan class, prime/subcontracted status and qualifier; physical citation; separate operative/current/analytics flags; semantic hash and M-2 lineage. Query promotion and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_medi_cal_managed_care_program_delivery_roster","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["occurrence_id"],"unmapped_key_tokens":["county_name","plan_ordinal","roster_year"],"backing_store":"glue"},{"source_id":"ca_smhs_1915b_legacy_history_period","source_fqn":"medicare_silver.ca_smhs_1915b_legacy_history_period","title":"California legacy SMHS 1915(b) authority-period history","domain":"state","stage":"silver","status":"live","grain":"One frozen corpus snapshot and source-stated legacy SMHS authority period.","description":"Production-reconciled and exact-replay-idempotent lossless chronology layer for the CA-17 initial authority through CA17.R09 temporary extensions. It preserves source-stated period text, independently parsed start/end dates, evidence basis, original-package recovery status, warnings, exact raw manifest JSON, semantic hashes, and M-2 lineage without manufacturing continuity or turning reconstructed dates into original authority documents.","identity_key":"corpus_snapshot_date,authority_id","row_count":13,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS or CMS publishes a newly recovered legacy artifact, corrects an index, or resolves a documented source limit.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate the official legacy and attachment indexes and bounded Wayback evidence; preserve each evidence class and never repair source-stated chronology by inference.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_smhs_1915b_legacy_history_period","known_gaps":["Production contains 13 reconciled history-period rows at Iceberg snapshot 1564840228996190499. Validation query `ac9f86e1-5280-4985-b521-e766f78a1740` proves zero duplicate certified-key groups and zero required-lineage null rows; exact replay returned `IDEMPOTENT_SKIP`, and snapshot proof query `084d6cb3-9668-4626-ba9c-3e4e08a5006f` preserved the snapshot. Hosted MCP data proof remains a separate post-merge rung.","R00-R03 and R05-R07 dates are reconstructed from the later R09 narrative; R04 is partially corroborated by its recovered approval letter, and R08 lacks a recovered standalone CMS approval/STCs package.","Source-stated chronology includes an R03/R04 overlap and other gaps. These are evidence, not errors to normalize into a continuous interval.","Archive capture timestamps are acquisition evidence only and must never become document, submission, approval, or effective dates.","This bounded history atom does not establish current authority, enrollment, claims, contracts, networks, capitation rates, or either California source family's completion."],"notes":"Production schema columns are corpus_snapshot_date, authority_id, period_text, period_start/end, date_basis, original_package_status, partial_original_evidence, warning, reconstruction/original-basis flags, manifest_sha256, raw_history_period_json, semantic_row_sha256, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_smhs_1915b_legacy_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date"],"unmapped_key_tokens":["authority_id"],"backing_store":"glue"},{"source_id":"ca_smhs_1915b_legacy_source_occurrence","source_fqn":"medicare_silver.ca_smhs_1915b_legacy_source_occurrence","title":"California legacy SMHS 1915(b) official source occurrences","domain":"state","stage":"silver","status":"live","grain":"One frozen corpus snapshot and official legacy DHCS/CMS source occurrence, including recovered, retrieval-limited, and expected-unrecovered artifacts.","description":"Production-reconciled and exact-replay-idempotent lossless occurrence ledger for the legacy CA-17 through CA17.R09 authority chain. It preserves authority and artifact roles; source-native date evidence; official, original, archive, and acquisition URLs; exact payload identity; content-alias ordinals; retrieval and expected-unrecovered source limits; eligibility and quality flags; raw occurrence JSON; semantic hashes; and M-2 lineage without inferring an operative-current roster.","identity_key":"corpus_snapshot_date,occurrence_id","row_count":38,"last_updated":"2026-08-01","freshness_sla":"Event-driven when DHCS or CMS publishes a newly recovered legacy artifact, corrects an index, or resolves a documented source limit.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate official indexes and bounded Wayback captures, pin exact payload bytes, and retain source limits and role/date evidence without relabeling or inference.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_smhs_1915b_legacy_source_occurrence","known_gaps":["Production contains 38 reconciled occurrence rows at Iceberg snapshot 4797273123761534803, including 33 recovered PDFs, four Incapsula retrieval limits, and one expected-unrecovered attachment. Validation query `ac9f86e1-5280-4985-b521-e766f78a1740` proves zero duplicate certified-key groups and zero required-lineage null rows; exact replay returned `IDEMPOTENT_SKIP`, and snapshot proof query `20fa1228-87a2-4159-9f4d-dea6b2dad383` preserved the snapshot. Hosted MCP data proof remains a separate post-merge rung.","R09 attachment 17 remains named but unrecovered. Its bytes, document SHA-256, pages, acquisition URL, and physical page rows remain absent rather than invented.","Four officially indexed 2020 extension-chain occurrences remain retrieval-limited by Incapsula. HTML challenge bytes are not accepted or hashed as PDFs.","A public notice, request, approval, amendment, technical correction, protocol, and package attachment are different roles and cannot be selected or summed as interchangeable authority actions.","Repeated physical content may deduplicate only by exact document SHA-256; every official occurrence, role, URL, and source limit remains addressable.","This source ends before CalAIM R10 and cannot establish current operative authority, observed program activity, or family completion."],"notes":"Production schema columns are corpus_snapshot_date, occurrence_id, authority_id, role, document-date fields and precision, date_basis, original/official/archive/acquisition URLs, byte_count, document_sha256, page expectations, payload status, source-limit reason, warning/request/effective fields, content alias ordinals, recovery/source-limit/eligibility flags, quality_flags, manifest/raw occurrence JSON/semantic hashes, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_smhs_1915b_legacy_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["corpus_snapshot_date","occurrence_id"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ca_smhs_1915b_legacy_pdf_page","source_fqn":"medicare_silver.ca_smhs_1915b_legacy_pdf_page","title":"California legacy SMHS 1915(b) physical PDF-page evidence","domain":"state","stage":"silver","status":"live","grain":"One exact recovered PDF document SHA-256 and one-based physical page number.","description":"Production-reconciled and exact-replay-idempotent lossless page layer for the 33 recovered legacy SMHS 1915(b) PDFs, preserving layout-aware extracted text, exact document and page-text hashes, word count, extraction method, quality flags, semantic hashes, canonical occurrence linkage, and M-2 lineage. It is physical citation evidence, not a structured operative-rule table.","identity_key":"document_sha256,page_number","row_count":1356,"last_updated":"2026-08-01","freshness_sla":"Event-driven with each separately accepted exact-byte recovery or correction to the frozen legacy corpus.","recollection":{"cadence":"event_driven","watermark_field":"corpus_snapshot_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Reparse only exact accepted PDF bytes, retain page and text hashes and extraction quality flags, and resolve authority semantics through the occurrence and history ledgers.","watermark_field 'corpus_snapshot_date' is the date of the frozen corpus snapshot the row belongs to (a Vlada acquisition vintage), not a DHCS or CMS publication, effective or approval date; those are independent date axes carried on the row."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ca_smhs_1915b_legacy_pdf_page","known_gaps":["Production contains 1,356 reconciled physical-page rows at Iceberg snapshot 7989364117211900127, including 14 `pypdf_plain_rotated_fallback` rows. Validation query `ac9f86e1-5280-4985-b521-e766f78a1740` proves zero duplicate certified-key groups and zero required-lineage null rows; exact replay returned `IDEMPOTENT_SKIP`, and snapshot proof query `f4d9a5f7-59b4-41cf-96f1-4635db7b4577` preserved the snapshot. Hosted MCP data proof remains a separate post-merge rung.","Retrieval-limited and expected-unrecovered occurrences emit no physical pages; absence must reconcile to the occurrence ledger and is not evidence of zero-page authority.","Layout extraction can preserve empty-text or rotated-text quality flags. Missing text must not be filled or treated as an absent legal provision without separately accepted OCR evidence.","Physical-page analytics eligibility is extraction fitness only, not legal operativity or evidence that a reconstructed period is an original authority artifact.","Content-identical occurrence aliases may share one page set, but physical deduplication must not erase their distinct roles and URLs in the occurrence ledger."],"notes":"Production schema columns are corpus_snapshot_date, document_sha256, canonical_occurrence_id, content_occurrence_count, page_number, page_text/page_text_sha256, word_count, extraction_method, semantic_row_sha256, quality_flags, is_analytics_eligible, plus the M-2 lineage envelope. Production reconciliation, unchanged-snapshot replay, query promotion, and source certification are proven; hosted MCP data proof remains gated.","superseded_by":null,"tools":[],"dataset_id":"ca_dhcs_smhs_1915b_legacy_authority","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["document_sha256","page_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ipps_payment_source_asset","source_fqn":"medicare_silver.ipps_payment_source_asset","title":"CMS IPPS Impact and inpatient PSF source/document inventory","domain":"medicare","stage":"silver","status":"live","grain":"One row per acquired top-level CMS asset or recursively indexed archive document.","description":"Complete physical source inventory for the accepted 79-asset CMS IPPS Impact and inpatient Provider Specific File corpus, expanding to 421 top-level and nested documents with publisher release, fiscal year, rule stage, snapshot date, format, bytes, SHA-256, parse disposition, source limits, current-release state, and exact Bronze lineage.","identity_key":"observed_period,asset_id,document_path","row_count":421,"last_updated":"2026-07-26","freshness_sla":"Re-inventory every accepted CMS Impact, PSF/PDS, and Claims Manual Addendum A publisher surface on each governed refresh.","recollection":{"cadence":"quarterly","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Re-enumerate official CMS surfaces, retain every release and archive member, deduplicate only identical source URLs, and require exact content hash, Bronze key, and S3 version lineage.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ipps_payment_source_asset","commercial_terms":"Public CMS hospital-payment rulemaking and provider-specific assets.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_ipps_impact_psf_2026_07_26.json","context_doc_path":"docs/context_library/medicare/ipps_impact_psf.md","known_gaps":["FY2003 and FY2004 official record-layout item pages currently expose no downloadable layout; their self-describing Excel provider data remain recoverable and no unofficial layout is substituted.","The 421 rows expand 79 top-level assets into physical documents, so top-level and recursive document counts are not interchangeable.","This is source lineage, not a hospital observation, claim, utilization fact, cost report, or AHD/AHA payer-revenue split."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_ipps_final_rule","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":["document_path"],"backing_store":"glue"},{"source_id":"ipps_impact_provider_row","source_fqn":"medicare_silver.ipps_impact_provider_row","title":"CMS IPPS Impact physical provider rows","domain":"medicare","stage":"silver","status":"live","grain":"One physical provider row per observed period, Impact asset, document, sheet, and source row.","description":"Full FY1994 through FY2027 proposed physical Impact history with 428,432 rows, retaining proposed/final/correction releases and alternate encodings plus promoted CCN, hospital name, wage area/index, teaching ratio, beds, DSH, uncompensated-care, CCR, case-mix, outlier, provider-type, hospital-specific-rate, and modeled-case fields alongside lossless raw headers and cells.","identity_key":"observed_period,asset_id,document_path,sheet_name,source_row_number","row_count":428432,"last_updated":"2026-07-26","freshness_sla":"Annual proposed/final IPPS rule refresh plus any CMS correction, supplemental, or interim release.","recollection":{"cadence":"event_driven","watermark_field":"fiscal_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Choose fiscal year, rule stage, release, document, and encoding before aggregation; preserve physical lineage and use is_analytics_eligible for provider rows.","watermark_field 'fiscal_year' is the IPPS rule fiscal year of the Impact file the row came from; proposed and final rule stages for the same fiscal_year coexist, so pin rule stage, release and document as well."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.ipps_impact_provider_row","commercial_terms":"Public CMS IPPS Impact files.","provenance_chain_ref":"docs/reference/source-audit/source-mastery/manifests/cms_ipps_impact_psf_2026_07_26.json","context_doc_path":"docs/context_library/medicare/ipps_impact_psf.md","known_gaps":["Impact values are rule-time payment models and may differ from factors ultimately used to pay claims.","Proposed, final, correction, and alternate TXT/XLS/XLSX encodings are separate physical evidence and must not be summed as distinct hospitals.","Modeled Medicare cases are not observed claims; Impact does not provide all-payer utilization, HCRIS revenue, or an AHD/AHA payer-revenue split."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_ipps_final_rule","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period","sheet_name","source_row_number"],"unmapped_key_tokens":["document_path"],"backing_store":"glue"},{"source_id":"inpatient_psf_provider_record","source_fqn":"medicare_silver.inpatient_psf_provider_record","title":"CMS inpatient Provider Specific File effective records","domain":"medicare","stage":"silver","status":"live","grain":"One full-history inpatient PSF record per accepted snapshot, source-native publisher provider identifier, and effective date.","description":"Effective-dated inpatient Provider Specific File history across the accepted current PDS export and quarterly full-history snapshots, retaining the publisher providerCcn identifier, effective/export/termination dates, provider type, geographic and wage assignments, teaching ratios, operating/capital CCRs, case mix, DSH, VBP/HRRP/HAC/EHR factors, uncompensated care, low-volume adjustment, county, NPI, exact raw fields, and Bronze lineage.","identity_key":"observed_period,snapshot_date,ccn,effective_date","row_count":3161162,"last_updated":"2026-07-26","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.inpatient_psf_provider_record","notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_inpatient_provider_specific_file","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":["effective_date","observed_period","snapshot_date"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"qualitynet_measure_methodology_source_asset","source_fqn":"medicare_silver.qualitynet_methodology_source_asset","title":"CMS QualityNet readmission-methodology source assets","domain":"medicare","stage":"silver","status":"live","grain":"One row per QualityNet content ID in the accepted methodology and reporting-resource corpus.","description":"Complete 69-content-ID inventory behind the 70 official QualityNet readmission methodology and resource page references posted from 2008 through 2026, retaining aliases, publisher dates and file types, exact source bytes and SHA-256, stable content endpoints, deterministic bundle lineage, and current-release state.","identity_key":"observed_period,content_id","row_count":69,"last_updated":"2026-06-03","freshness_sla":"Re-inventory both QualityNet public gateway pages and every stable content endpoint on each governed refresh.","recollection":{"cadence":"event_driven","watermark_field":"posted_date","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Enumerate both official page APIs, deduplicate only by content ID, retain every page alias, and require exact source bytes, content hash, and Bronze lineage.","watermark_field 'posted_date' is the posted date QualityNet publishes with the content item, as carried in the publisher reference; it is publisher metadata, not the date Vlada acquired the bytes (asserted_at)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.qualitynet_methodology_source_asset","commercial_terms":"Public CMS QualityNet methodology and reporting-resource assets.","known_gaps":["This is methodology/reference logic, not hospital scores, patient claims, payment amounts, CCN-level utilization, HCRIS revenue, or an AHD-style payer revenue split.","One publisher content ID is referenced by two QualityNet page labels and is acquired once while both aliases remain in page_references_json.","The stable content endpoint is durable source identity; short-lived publisher download URLs must never be stored as that identity."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_qualitynet_readmission_methodology","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["content_id"],"backing_store":"glue"},{"source_id":"qualitynet_measure_methodology_document","source_fqn":"medicare_silver.qualitynet_methodology_document","title":"CMS QualityNet methodology document and archive-member inventory","domain":"medicare","stage":"silver","status":"live","grain":"One row per QualityNet content ID and deterministic top-level or recursive document ordinal.","description":"Lossless inventory of 427 top-level QualityNet files and safely traversed archive members, retaining parent/member identity, archive depth, exact path, actual format, bytes, hash, page and worksheet counts, parse disposition, measure family, quality flags, and source lineage.","identity_key":"observed_period,content_id,document_ordinal","row_count":427,"last_updated":"2026-06-03","freshness_sla":"Rebuild from the complete deterministic source bundle on each governed QualityNet refresh.","recollection":{"cadence":"event_driven","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Traverse archives with path, depth, expansion, and member-size guards; sniff OOXML by package content rather than suffix and retain zero-byte publisher members as explicit quality rows.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.qualitynet_methodology_document","commercial_terms":"Public CMS QualityNet files and archive members.","known_gaps":["The official 2019 archive contains a zero-byte XLSX name plus a valid OOXML workbook carrying a .partial suffix; both physical members are preserved and the valid package is parsed by content.","A deterministic document ordinal is part of the physical key because ZIP archives can legally contain duplicate member paths.","A document row proves publisher content and parse disposition, not adoption of a proposed measure or hospital performance."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_qualitynet_readmission_methodology","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["content_id","document_ordinal"],"backing_store":"glue"},{"source_id":"qualitynet_measure_methodology_document_text","source_fqn":"medicare_silver.qualitynet_methodology_document_text","title":"CMS QualityNet searchable methodology document text","domain":"medicare","stage":"silver","status":"live","grain":"One row per QualityNet document and extractable PDF page or Office/text segment.","description":"Searchable 7,320-segment history of QualityNet methodology reports, factsheets, user guides, reporting resources, and supporting Office/text documents, retaining page or segment identity, exact text fingerprint, measure family, current-release state, analytics eligibility, and source lineage.","identity_key":"observed_period,content_id,document_ordinal,segment_number","row_count":7320,"last_updated":"2026-06-03","freshness_sla":"Re-extract from every accepted document on each governed QualityNet refresh.","recollection":{"cadence":"event_driven","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve page/segment order, content ID, document ordinal, measure family, release state, and exact text hash; never infer adoption or hospital applicability from text presence.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.qualitynet_methodology_document_text","commercial_terms":"Public CMS QualityNet document text.","known_gaps":["Text is publisher methodology and reporting guidance, not a hospital score, patient event, coverage decision, or payment determination.","Proposed sepsis methodology text remains distinguishable from adopted production specifications.","Empty or non-extractable publisher members remain documented in the document inventory and are not replaced with inferred text."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_qualitynet_readmission_methodology","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["content_id","document_ordinal","segment_number"],"backing_store":"glue"},{"source_id":"qualitynet_measure_methodology_table_row","source_fqn":"medicare_silver.qualitynet_methodology_table_row","title":"CMS QualityNet readmission-methodology spreadsheet rows","domain":"medicare","stage":"silver","status":"live","grain":"One row per QualityNet document, worksheet, and physical nonblank source row.","description":"Lossless 2,498,682-row history of QualityNet cohort, exclusion, risk-variable, planned-readmission, POA, frailty, CC, CCS-to-ICD, and related spreadsheet logic, retaining titles, notes, headers, raw cells, conservative measure/rule/code normalization, semantic fingerprints, quality flags, and exact physical lineage.","identity_key":"observed_period,content_id,document_ordinal,sheet_ordinal,source_row_number","row_count":2498682,"last_updated":"2026-06-03","freshness_sla":"Rebuild from all accepted QualityNet workbooks and archive members on each governed refresh.","recollection":{"cadence":"event_driven","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve every nonblank physical row, raw cells, document/sheet/row lineage, reporting year, measure family, rule role, and code system; use is_analytics_eligible for analytic rows and semantic_row_sha256 only for explicit consumer deduplication.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.qualitynet_methodology_table_row","commercial_terms":"Public CMS QualityNet spreadsheet methodology and reference logic.","known_gaps":["A code row is reporting-year methodology logic, not evidence that a hospital treated a patient, received payment, met a coverage rule, or has a CCN-level result.","Reporting year is not automatically an ICD effective date; governed joins require code system, normalized code, and compatible reporting/effective periods.","Repeated rows across separate measure workbooks are legitimate source-native methodology rows and must not be deduplicated on code alone.","Source workbooks contain formatting-only terminal rows and inflated dimensions; bounded content-aware parsing retains semantic rows and records exact quality flags without materializing formatting-only cells."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_qualitynet_readmission_methodology","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_row_number"],"unmapped_key_tokens":["content_id","document_ordinal","sheet_ordinal"],"backing_store":"glue"},{"source_id":"cssc_operations_reference_source_asset","source_fqn":"medicare_silver.cssc_operations_source_asset","title":"CMS CSSC Part C operations governed source-asset ledger","domain":"medicare","stage":"silver","status":"live","grain":"One row per accepted release asset, governed source limit, deferred atomic lane, or existing Vlada overlap.","description":"Content, rights, and overlap ledger for the accepted public CSSC Part C operations corpus: 28 acquired public CSSC assets, five metadata-only external-code or implementation-guide limits, three existing-source pointers, and two separately deferred operational worlds.","identity_key":"observed_period,asset_id","row_count":38,"last_updated":"2026-07-24","freshness_sla":"Re-inventory all current/archive CSSC Part C, EDI, listserv, job-aid, video, and lookup surfaces on each governed refresh.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Refresh must preserve each asset's maintainer and license class and fail closed if any governed source-limit asset claims acquired payload or a bundle member.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_operations_source_asset","commercial_terms":"Public CMS/CSSC payload only. X12 implementation-guide and code-list content, AMA CPT, ADA CDT, and AHA/NUBC descriptions are not acquired or served.","known_gaps":["Five X12/AMA/ADA/NUBC-related families are metadata-only source limits with no payload member; the table is a rights ledger, not a licensed decoder.","Part D/DDPS/NCPDP/PDFS and FAI operations are separate deferred atomic sources and are not silently mixed into Part C.","Existing diagnosis, CARC-boundary, and institutional-code sources remain independently mastered and are referenced rather than duplicated."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["asset_id","observed_period"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cssc_operations_reference_resource","source_fqn":"medicare_silver.cssc_operations_resource","title":"CMS CSSC Part C article, listserv, job-aid, and video history","domain":"medicare","stage":"silver","status":"live","grain":"One row per publisher context and CSSC document identifier (DID).","description":"Lossless metadata and body-fingerprint index for 911 distinct CSSC resources across eight bounded current/archive collections from 2003 through 2026, retaining listing dates, article dates, body presence, attachment counts, collection identity, and exact Bronze lineage.","identity_key":"observed_period,publisher_context,did","row_count":911,"last_updated":"2026-07-24","freshness_sla":"Re-inventory current and archived CSSC collections on each governed refresh.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Retain publisher_context with DID because current/archive contexts are separate publisher surfaces; do not infer missing article bodies.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_operations_resource","commercial_terms":"Public CSSC publisher metadata and article-body fingerprints.","known_gaps":["Eleven publisher resources have an empty article body and remain explicit body_present=false quality rows rather than being dropped or backfilled from another release.","Resource dates are publisher listing/article metadata and are not encounter service dates, claim dates, or code effective dates.","A resource row indexes public CSSC guidance; it is not proof that a plan submitted an encounter or that an edit fired."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["did","publisher_context"],"backing_store":"glue"},{"source_id":"cssc_operations_reference_attachment","source_fqn":"medicare_silver.cssc_operations_attachment","title":"CMS CSSC resource attachment-link index","domain":"medicare","stage":"silver","status":"live","grain":"One row per CSSC resource and HTML anchor ordinal.","description":"Lossless 1,002-row link index extracted from the 911 accepted CSSC article bodies, retaining raw and resolved URLs, link text, host, file metadata, acquisition disposition, source-limit status, and article-member lineage.","identity_key":"observed_period,publisher_context,did,attachment_ordinal","row_count":1002,"last_updated":"2026-07-24","freshness_sla":"Rebuild with the complete resource corpus on each governed CSSC refresh.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Recollection must preserve raw href, resolved URL, article identity, and physical anchor ordinal; payload acquisition remains separately governed.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_operations_attachment","commercial_terms":"Public link metadata only; linked external or licensed payload is not acquired merely because CSSC exposes a hyperlink.","known_gaps":["This is an attachment-link index, not a claim that every linked file was acquired, parsed, current, or licensed for redistribution.","Preserve acquisition_disposition and source_limit before following a link; public hyperlink visibility does not override X12, AMA, ADA, or NUBC rights.","Attachment ordinals are physical HTML-anchor lineage and must not be collapsed by URL."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period"],"unmapped_key_tokens":["attachment_ordinal","did","publisher_context"],"backing_store":"glue"},{"source_id":"cssc_operations_reference_operational_edit","source_fqn":"medicare_silver.cssc_operational_edit","title":"CMS CSSC public EDPS, RAPS, and FERAS operational edits","domain":"medicare","stage":"silver","status":"live","grain":"One row per public lookup asset and physical JSON source row.","description":"Public CMS-authored CSSC operational edit rows for EDPS institutional, professional, DME, and dental submissions plus RAPS and FERAS, retaining system, data type, edit code, disposition, effective history, resolution text, physical source row, and raw JSON.","identity_key":"observed_period,source_asset_id,source_row_number","row_count":679,"last_updated":"2026-07-24","freshness_sla":"Snapshot the public CSSC lookup endpoints on each governed refresh and retain physical disposition/effective-history rows.","recollection":{"cadence":"snapshot_adhoc","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Join with system, data_type, source asset, and physical history; never deduplicate on edit_code alone or reconstruct excluded external code sets.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_operational_edit","commercial_terms":"Public CMS/CSSC edit semantics only. X12 837/277CA/TA1, CARC, AMA CPT, ADA CDT, and AHA/NUBC payload is excluded.","known_gaps":["Edit code alone is not a unique key; EDPS legitimately repeats codes across physical disposition or effective-history rows and those rows must be retained.","The table supports submission validation and troubleshooting; it does not contain encounters, beneficiaries, plan payment, adjudication outcomes, or claim frequency.","Licensed X12 and externally maintained code descriptions remain excluded even when a CSSC page references them."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cssc_operations_reference_acceptable_specialty","source_fqn":"medicare_silver.cssc_acceptable_specialty","title":"CMS CSSC acceptable physician specialty history","domain":"medicare","stage":"silver","status":"live","grain":"One row per payment-year document and physical specialty-code row.","description":"Complete accepted CSSC acceptable-physician-specialty history for payment years 2016 through 2025, retaining service year, code, description, skipped-number marker, document page, physical row, raw row, release identity, and exact Bronze lineage.","identity_key":"observed_period,source_asset_id,source_row_number","row_count":794,"last_updated":"2026-07-24","freshness_sla":"Annual payment-year release; re-inventory publisher history on each governed refresh.","recollection":{"cadence":"annual","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Interpret specialty codes within the documented payment/service year and retain physical row and page lineage.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_acceptable_specialty","commercial_terms":"Public CMS/CSSC specialty-list content.","known_gaps":["Payment year and service year are distinct source fields and must both be retained for temporal interpretation.","Acceptable-for-submission status is not proof that a clinician has that specialty or that an encounter was valid, paid, or risk-adjustment eligible.","Preserve source document and row identity; do not collapse the annual physical history into one timeless specialty list."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cssc_operations_reference_sbsc_code","source_fqn":"medicare_silver.cssc_sbsc_code","title":"CMS CSSC Supplemental Benefit Service Category submission codes","domain":"medicare","stage":"silver","status":"live","grain":"One row per contract-year revision and physical SBSC code row.","description":"Public CSSC SBSC encounter/reporting submission taxonomy for the initial and August 2024 revisions plus contract years 2025 and 2026, retaining revision identity, code, description, source notes, physical row, raw content, current-release state, and a mandatory PBP semantic-safety label.","identity_key":"observed_period,source_asset_id,source_row_number","row_count":403,"last_updated":"2026-07-24","freshness_sla":"Annual contract-year publication plus in-year revisions; retain every distinct revision and explicit current-release status.","recollection":{"cadence":"event_driven","watermark_field":"observed_period","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Annual contract-year releases and in-year revisions are both events. Every row must retain pbp_semantic_status=operational_submission_code_not_evidence_of_benefit_offer_amount_or_moop; never project SBSC presence to a plan benefit.","watermark_field 'observed_period' is the M-2 envelope column for the period the data describes, here the accepted publisher release or corpus snapshot the row was parsed from (docs/architecture/2026-05-09-medicare-substrate-m2-temporal-triplet.md); asserted_at is the date that bytes-version was published."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.cssc_sbsc_code","commercial_terms":"Public CMS/CSSC submission-code content.","known_gaps":["SBSC is an encounter/reporting submission taxonomy and is not evidence that a plan offers a benefit, a benefit amount, member cost share, utilization, PMPM value, combined limit, or MOOP treatment.","A null or absent PBP numeric amount is not $0; benefit interpretation remains in the governed PBP/MPF/SB/EOC/ANOC reconciliation layer, not this table.","Contract years 2025 and 2026 code 18c preserves the publisher note that the reporting code is not part of that contract year's PBP.","The initial and August 2024 revisions are both retained; only the August revision is current for that contract year."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_cssc_operations_reference","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["observed_period","source_asset_id","source_row_number"],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"ahrq_nhqdr_quality","source_fqn":"medicare_silver.fact_ahrq_nhqdr_quality","title":"AHRQ NHQDR national and state quality estimates","domain":"medicare","stage":"silver","status":"live","grain":"One row per accepted Tableau publisher extract, physical page, and physical row ordinal.","description":"Lossless 855,292-row extract of the official AHRQ National Healthcare Quality and Disparities Report logical table, preserving 666 measures, national and 59 state/territory jurisdiction labels, population subgroups, raw/formatted estimates, error values, footnotes, source links, physical row identity, and exact lineage for data years 1999-2022.","identity_key":"publisher_extract_id,source_page_number,source_row_ordinal","row_count":855292,"last_updated":"2026-08-09","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_ahrq_nhqdr_quality","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ahrq_nhqdr","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["publisher_extract_id","source_page_number","source_row_ordinal"],"backing_store":"glue"},{"source_id":"state_quality_publisher_semantic","source_fqn":"medicare_semantic.vw_state_quality_publisher","title":"Publisher-native state quality measures","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per publisher, state, reporting year, program/population/methodology, and measure observation.","description":"Governed standard view over AHRQ NHQDR estimates, CMS Medicaid/CHIP Child and Adult Core Set state rates, Medicaid Health Home program quality cells, and CDC NHSN state HAI progress ratios, preserving raw values, sentinels, methodology, setting, ratio type, physical publisher-observation identity, and exact atomic lineage.","identity_key":"source_id,source_observation_key","row_count":596762,"last_updated":"2026-08-09","freshness_sla":"Refresh after either accepted atomic source publishes a new governed vintage.","recollection":{"cadence":"derived","watermark_field":"asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve publisher-native value status and raw value; null, DS, NR, #, NA, and insufficient denominator are not zero.","watermark_field 'asserted_at' is the underlying atomic source's M-2 publication date carried through the view; the view is derived, so it is exactly as fresh as its accepted inputs."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_state_quality_publisher","commercial_terms":"Public CMS and CDC quality data; freely downloadable.","known_gaps":["The view standardizes AHRQ NHQDR 1999-2022, NHSN 2009-2024, Medicaid/CHIP Core Set 2019-2024, and Medicaid Health Home 2019-2024.","Publisher-native state observations are never pooled into a composite rank.","Four publisher-ambiguous NHSN rows remain in the atomic table and are excluded from this analytics view."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_state_quality","dataset_assignment_basis":"source_id_prefix","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["source_observation_key"],"backing_store":"glue"},{"source_id":"state_quality_rollup_semantic","source_fqn":"medicare_semantic.vw_state_quality_rollup","title":"CMS provider and clinician state quality distributions","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per source, provider-location state, reporting-period type, reporting period, and measure.","description":"Explicitly Vlada-derived unweighted state distributions across 12 certified CMS quality families covering hospitals, QPP/MIPS clinicians or groups, nursing homes, home health, hospice, dialysis facilities, and ESRD QIP.","identity_key":"source_id,state_code,reporting_period_type,reporting_period,measure_id","row_count":259838,"last_updated":"2026-08-09","freshness_sla":"Refresh after any underlying certified CMS quality family changes schema or publishes a new accepted vintage.","recollection":{"cadence":"derived","watermark_field":"source_asserted_at","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["No cross-measure pooling; no hidden beneficiary weighting; observed and missing counts must remain visible.","watermark_field 'source_asserted_at' is the M-2 asserted_at of the underlying certified CMS quality family row, carried through the rollup; the view is derived and only as fresh as that input."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_state_quality_rollup","commercial_terms":"Derived from public CMS quality data; freely downloadable source substrate.","known_gaps":["Provider or practice location is not beneficiary residence and must not be labeled as a resident outcome rate.","Distributions are unweighted source-record summaries; they do not reproduce claims-attributed longitudinal physician outcomes.","Source-native units remain measure-specific and are never pooled into a universal state score.","Records with unknown geography remain in atomic tables and are excluded from state distributions."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_state_quality","dataset_assignment_basis":"source_id_prefix","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state_code"]},"technical_keys":["source_id"],"unmapped_key_tokens":["measure_id","reporting_period","reporting_period_type"],"backing_store":"glue"},{"source_id":"curated_dim_contract","source_fqn":"vlada_curated.dim_contract","title":"Medicare contract dimension","domain":"medicare","stage":"dim","status":"live","grain":"One row per Medicare contract_id — the authority for cms:contract_id.","description":"The resolving dimension for Medicare contract_id, built because 89 catalogued assets carried the identifier and nothing defined it. Population is the UNION of contract_id observed across seven sources (monthly contract enrollment, stars contracts, MA contract service area, plan- and county-level enrollment, landscape, SNP), because per-source counts disagree by up to 300 and no single source is authoritative. Attributes are LAST OBSERVED with the observation month carried alongside, so staleness is visible rather than assumed; they are not modelled per year, which would make this a slowly-changing fact and fan out every join through it.","identity_key":"contract_id","row_count":2166,"last_updated":"2026-08-15","raw_queryable_via":"Athena (read-only): vlada_curated.dim_contract","notes":"Measured 2026-08-15 at 100.0% coverage against six contract-carrying fact assets. Built by ops/scripts/build_dim_contract.py using the versioned pattern; the view repoints and nothing is dropped.","superseded_by":null,"tools":[],"dataset_id":"vlada_spine_medicare_contract_authority","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:contract_id"],"entity_key_columns":{"cms:contract_id":["contract_id"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"curated_dim_hcpcs","source_fqn":"vlada_curated.dim_hcpcs","title":"HCPCS code dimension","domain":"curated","stage":"dim","status":"live","grain":"One row per HCPCS code — the authority for cms:hcpcs.","description":"The resolving dimension for HCPCS, built because 19 catalogued assets carried the identifier and the only candidate authority was dim_provider_service, a provider-by-service fact holding roughly 1,988 rows per code. Population is the union of codes across the PFS RVU, OPPS Addendum B, ASC Addendum, CLFS and ASP fee schedules plus the provider-service fact. Descriptions are taken in source precedence, a CMS fee-schedule descriptor before a claims-aggregate label, and description_source records which supplied it.","identity_key":"hcpcs_code","row_count":24855,"last_updated":"2026-08-15","freshness_sla":"Rebuilt when any contributing fee schedule refreshes.","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt from the annual fee-schedule refreshes; the code set only grows."]},"raw_queryable_via":"Athena (read-only): vlada_curated.dim_hcpcs","commercial_terms":"Public CMS data. Level I (CPT) descriptors are AMA-copyrighted; only short descriptors published by CMS in its fee schedules are carried.","provenance_chain_ref":"Derived; each contributing fee schedule carries its own M-2 chain.","context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["2,376 codes match neither the Level I nor Level II pattern and are typed 'unknown' rather than dropped.","5 codes carry no description because no contributing source published one.","Descriptions are short descriptors, not the full CPT long descriptors, which are AMA-licensed."],"notes":"Measured 2026-08-15 at 100.0% coverage over five HCPCS-carrying assets, uniqueness 1.0. Built by ops/scripts/build_dim_hcpcs.py; every source read is pinned to is_current where the column exists.","superseded_by":null,"tools":[],"dataset_id":"vlada_spine_billing_code_vocabulary","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:hcpcs"],"entity_key_columns":{"cms:hcpcs":["hcpcs_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"curated_dim_provider_ccn","source_fqn":"vlada_curated.dim_provider_ccn","title":"Medicare provider CCN dimension (all provider types)","domain":"provider_identity","stage":"dim","status":"live","grain":"One row per Medicare CCN across ALL provider types — the authority for cms:ccn.","description":"The resolving dimension for Medicare CCNs of every provider type, built because cms:ccn is a family rather than one identifier. A CCN identifies a Medicare-certified provider and the type is encoded in the number, so the hospital identity dimension resolved hospitals at 99.9% and SNF, home-health, hospice, FQHC, RHC, ASC and dialysis rosters at roughly 0%. Built as the union of the ten rosters we already hold, each authoritative for its own type, rather than from CMS positional range conventions.","identity_key":"ccn","row_count":101528,"last_updated":"2026-08-15","freshness_sla":"Rebuilt when any contributing POS roster refreshes (quarterly).","recollection":{"cadence":"quarterly","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Rebuilt from the quarterly CMS Provider of Services rosters."]},"raw_queryable_via":"Athena (read-only): vlada_curated.dim_provider_ccn","commercial_terms":"Public CMS data.","provenance_chain_ref":"Derived; each contributing roster carries its own M-2 chain.","context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["513 CCNs (0.5%) appear in more than one roster, overwhelmingly LTCH and IRF facilities that are also hospitals. The most specific roster wins; all_provider_types retains every roster that claimed the CCN.","provider_type is evidenced by which roster carried the CCN, not decoded from the CCN positional ranges.","Coverage follows the rosters. A provider type we hold no roster for is absent."],"notes":"Measured 2026-08-15 - every roster that scored roughly 0% against the hospital dimension scores 100.0% here, and the hospital mart holds at 99.9%. Built by ops/scripts/build_dim_provider_ccn.py; every source read is pinned to is_current where the column exists.","superseded_by":null,"tools":["resolve_provider"],"dataset_id":"vlada_w5_identity_graph","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["cms:ccn"],"entity_key_columns":{"cms:ccn":["ccn"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"curated_dim_state","source_fqn":"vlada_curated.dim_state","title":"US state and territory dimension","domain":"curated","stage":"dim","status":"live","grain":"One row per USPS state or territory code — the authority for usps:state.","description":"The resolving dimension for USPS state codes, built because the only candidate authority was dim_state_metric, a metrics fact grained (state_code, domain, metric) holding roughly 37 rows per state. Population is dim_geography's state set unioned with every state code actually observed in the assets that use the identifier, so a state referenced by a metrics table but absent from the ZIP-derived geography is still resolvable.","identity_key":"state_code","row_count":56,"last_updated":"2026-08-15","freshness_sla":"Static; rebuilt when dim_geography refreshes.","recollection":{"cadence":"annual","watermark_field":null,"freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Static reference; changes only when dim_geography is rebuilt."]},"raw_queryable_via":"Athena (read-only): vlada_curated.dim_state","commercial_terms":"Public Census and USPS reference data.","provenance_chain_ref":"Derived from vlada_curated.dim_geography.","context_doc_path":"docs/context_library/curated/core_curated_dims.md","known_gaps":["56 codes = 50 states, DC and 5 territories. Coverage follows what our data references, not the full USPS code list.","attribute_source records whether a code came from dim_geography or was observed only in a metrics table; the latter carries null attributes rather than invented ones."],"notes":"Built by ops/scripts/build_dim_state.py. Population derived from data rather than written from memory, for the same reason dim_provider_ccn was built from rosters instead of CMS range conventions.","superseded_by":null,"tools":[],"dataset_id":"vlada_spine_geography_hierarchy","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state_code"]},"technical_keys":[],"unmapped_key_tokens":[],"backing_store":"glue"},{"source_id":"cms_marketplace_issuer_plan_enrollment_history","source_fqn":"medicare_silver.fact_marketplace_plan_enrollment_measure_history","title":"CMS Marketplace issuer and plan enrollment measure history","domain":"commercial","stage":"silver","status":"live","grain":"One source-native plan measure observation per business year, platform, issuer, plan, workbook sheet row, and immutable workbook artifact.","description":"CMS annual Marketplace plan-level enrollment measures across federal-platform and independent state-based Marketplace workbooks through business year 2025, preserving measure eras, suppression, exact plan identifiers, and workbook/Bronze lineage.","identity_key":"source_id,source_workbook_sha256,workbook_sheet,source_row_number,source_measure_name","row_count":233906,"last_updated":"2026-08-31","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Changed workbook bytes coexist as a new immutable artifact; repeated identical cumulative SBM data units do not create duplicate facts.","Never substitute the state-level monthly file for issuer or plan data.","watermark_field 'business_year' is the Marketplace plan (business) year the enrollment measure was published for; it is not the workbook release date, which is carried by the immutable artifact identity."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_marketplace_plan_enrollment_measure_history","known_gaps":["The physical history has is_current=false on every accepted row; do not filter is_current=true. No semantic current view is published.","Suppressed asterisk values are unknown counts of ten or fewer with numeric_value=null, not zero; numeric sums are lower bounds.","The 2021 parallel federal methodologies must remain separate and qualified.","Plan rows and issuer-geography rows are separate, non-additive facts.","The accepted parent bridge and Plan Attributes analytical joins are not published by this source release.","PY2026 issuer-level data was not yet published as of August 31, 2026."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_marketplace_issuer_level_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id","source_row_number"],"unmapped_key_tokens":["source_measure_name","source_workbook_sha256","workbook_sheet"],"backing_store":"glue"},{"source_id":"cms_marketplace_issuer_geography_enrollment_history","source_fqn":"medicare_silver.fact_marketplace_issuer_geography_enrollment_measure_history","title":"CMS Marketplace issuer geography enrollment measure history","domain":"commercial","stage":"silver","status":"live","grain":"One source-native issuer geography measure observation per business year, federal platform, issuer, county or state-total, workbook sheet row, and immutable workbook artifact.","description":"CMS annual federal-platform issuer-by-county and issuer-state-total Marketplace enrollment and demographic measures through business year 2025, preserving suppression, geography grain, measure eras, and workbook/Bronze lineage.","identity_key":"source_id,source_workbook_sha256,workbook_sheet,source_row_number,source_measure_name","row_count":3296584,"last_updated":"2026-08-31","recollection":{"cadence":"annual","watermark_field":"business_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Preserve county, state-total, and unknown-county grains separately.","Never project issuer geography to individual plans.","watermark_field 'business_year' is the Marketplace plan (business) year the issuer geography measure was published for; it is not the workbook release date, which is carried by the immutable artifact identity."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_marketplace_issuer_geography_enrollment_measure_history","known_gaps":["The physical history has is_current=false on every accepted row; do not filter is_current=true. No semantic current view is published.","Federal issuer-county rows do not identify a plan, and independent-SBM plan rows do not publish county geography.","County rows and issuer-state-total rows must not be added together.","Suppressed asterisk values are unknown counts of ten or fewer; numeric geographic sums are lower bounds.","This release publishes no issuer-to-parent edge and no plan-county edge."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_marketplace_issuer_level_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id","source_row_number"],"unmapped_key_tokens":["source_measure_name","source_workbook_sha256","workbook_sheet"],"backing_store":"glue"},{"source_id":"cms_marketplace_monthly_effectuated_enrollment_history","source_fqn":"medicare_silver.fact_marketplace_monthly_effectuated_enrollment_history","title":"CMS Marketplace monthly effectuated enrollment release history","domain":"commercial","stage":"silver","status":"live","grain":"One state-or-publisher-total by platform, coverage year, and coverage month observation inside one immutable CMS release artifact.","description":"CMS rolling monthly Marketplace effectuated enrollment by state and exchange platform from January 2016 through February 2026 in the accepted release, retaining release identity, publisher totals, and Bronze lineage.","identity_key":"source_id,source_artifact_sha256,state_code,platform,coverage_year,coverage_month","row_count":6588,"last_updated":"2026-08-31","raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_marketplace_monthly_effectuated_enrollment_history","notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_marketplace_monthly_effectuated_enrollment","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":["usps:state"],"entity_key_columns":{"usps:state":["state_code"]},"technical_keys":["source_id"],"unmapped_key_tokens":["coverage_month","coverage_year","platform","source_artifact_sha256"],"backing_store":"glue"},{"source_id":"ga_georgia_access_puf","source_fqn":"ga_georgia_access_puf","title":"Georgia Access Marketplace PUF — direct state publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One logical source-native CSV row within one immutable Georgia Access artifact, family, and plan year.","description":"Georgia Access direct PY2025-PY2026 Marketplace plan-management exports across Benefits and Cost Sharing, Rate, Plan Attributes, Business Rules, Service Area, Network, Plan ID Crosswalk, Machine-Readable URL and Quality families. This source remains distinct from CMS independent-SBE Georgia packages.","identity_key":"source_id,plan_year,family,source_artifact_sha256,source_row_number","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no Georgia-direct Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_ga_georgia","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["plan_year","source_id","source_row_number"],"unmapped_key_tokens":["family","source_artifact_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"va_vim_enrollment_metrics","source_fqn":"va_vim_enrollment_metrics","title":"Virginia Insurance Marketplace enrollment metrics — state publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native metric observation within one immutable Virginia artifact, publisher snapshot/as-of date, page and source row or metric ID.","description":"Virginia Insurance Marketplace PY2024 quarterly/OE and two byte-distinct but semantically equal PY2025 metric-ID static revisions, plus a separately resolved public Power BI model containing Open Enrollment PY2024-PY2026, quarterly 2025-Q1 through 2026-Q2 and source dictionaries. Pre-PY2024 federal-platform history retains CMS lineage.","identity_key":"source_id,source_artifact_sha256,plan_year,snapshot_label,metric_id_or_source_page_row","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no Virginia-direct Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_va_vim","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["plan_year","source_id"],"unmapped_key_tokens":["metric_id_or_source_page_row","snapshot_label","source_artifact_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"ky_khbe_governors_metrics","source_fqn":"ky_khbe_governors_metrics","title":"Kentucky KHBE Governor's Metrics — monthly state publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native metric observation within one immutable Kentucky workbook, report period, sheet, source row and metric-header column.","description":"Forty-seven exact Kentucky Health Benefit Exchange workbooks covering 46 monthly semantic units and 232,590 non-duplicated QHP/Medicaid metric observations by program, plan, issuer/metal, county, age, gender and FPL, with Logic/Glossary revision context.","identity_key":"source_id,source_artifact_sha256,report_period,sheet_name,source_row_number,metric_column_index","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no Kentucky Governor's Metrics Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_ky_khbe","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["sheet_name","source_id","source_row_number"],"unmapped_key_tokens":["metric_column_index","report_period","source_artifact_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"ca_covered_california_enrollment_profiles","source_fqn":"ca_covered_california_enrollment_profiles","title":"Covered California enrollment profiles — state publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native observation within one immutable Covered California workbook, profile family, publisher period, sheet and source cell or row.","description":"Covered California Open Enrollment, active paid/effective member, Medi-Cal transitioner and special-enrollment profile history with issuer, plan, geography, subsidy and demographic detail.","identity_key":"source_id,source_artifact_sha256,profile_family,publisher_period,sheet_name,source_cell_or_row","row_count":null,"last_updated":"2026-09-07","raw_queryable_via":"Not queryable: no Covered California Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_ca_covered","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["sheet_name","source_id"],"unmapped_key_tokens":["profile_family","publisher_period","source_artifact_sha256","source_cell_or_row"],"backing_store":"logical_not_ingested"},{"source_id":"nj_getcoverednj_enrollment","source_fqn":"nj_getcoverednj_enrollment","title":"Get Covered New Jersey enrollment — state exchange history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native observation within one immutable New Jersey exchange PDF, carrier quarter or OE checkpoint, measure, unit and optional HIOS/metal/assistance dimension.","description":"Quarterly HIOS carrier policies and members plus Open Enrollment renewal, new-selection, financial-assistance, metal and Medicaid/CHIP transfer checkpoints for PY2021-PY2026.","identity_key":"source_id,source_artifact_sha256,publication_family,publisher_period,measure,unit,hios_or_dimension","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no Get Covered New Jersey Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_nj_getcoverednj","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["hios_or_dimension","measure","publication_family","publisher_period","source_artifact_sha256","unit"],"backing_store":"logical_not_ingested"},{"source_id":"nj_dobi_ihc_enrollment","source_fqn":"nj_dobi_ihc_enrollment","title":"New Jersey DOBI IHC enrollment — on/off-exchange history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native individual-market observation within one immutable NJDOBI IHC artifact, quarter, market scope, measure and optional carrier/plan dimension.","description":"New Jersey individual-market covered lives, source-native Plans and policy/contract operating measures from 1993 Q4 forward; ten exact parser families yield 30,198 physical observations from all 173 retrievable unique artifacts including cumulative revisions and two off-index 2021 Q2 recoveries.","identity_key":"source_id,source_artifact_sha256,publisher_period,market_scope,measure,hios_or_dimension","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no NJDOBI IHC Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_nj_dobi","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["hios_or_dimension","market_scope","measure","publisher_period","source_artifact_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"wa_hbe_enrollment_reports","source_fqn":"wa_hbe_enrollment_reports","title":"Washington Health Benefit Exchange enrollment reports — state publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native observation within one immutable Washington HBE workbook or report, release, sheet/cell, period, population, measure and optional geography/carrier/dimension.","description":"Washington Healthplanfinder QHP, Apple Health, dental, carrier, county, subsidy, premium, demographic, movement and Cascade Care reporting; all 51,568 populated cells in eight exact spring/fall workbooks are losslessly profiled, with 935 spring-core observations normalized separately and five unique legacy PDFs Wayback-recovered.","identity_key":"source_id,source_artifact_sha256,release_label,worksheet,source_cell,period,population,measure,dimension","row_count":null,"last_updated":"2026-09-07","raw_queryable_via":"Not queryable: no Washington HBE Bronze, registry, Iceberg history, semantic view, API or MCP surface has been accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_wa_hbe","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["period","source_id"],"unmapped_key_tokens":["dimension","measure","population","release_label","source_artifact_sha256","source_cell","worksheet"],"backing_store":"logical_not_ingested"},{"source_id":"ny_nysoh_enrollment_data","source_fqn":"ny_nysoh_enrollment_data","title":"NY State of Health enrollment reports — direct publisher history","domain":"commercial","stage":"silver","status":"planned","grain":"One source-native EP, QHP or dental enrollment observation within one immutable official PDF, report period, geography, issuer and measure.","description":"One hundred three official NY State of Health enrollment PDFs, including a parsed 37-report statewide Essential Plan and QHP current-enrollment series from March 2023 through August 2026.","identity_key":"source_id,source_artifact_sha256,coverage_month,geography_type,geography_value,hios_or_all,measure,unit","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: exact source evidence exists, but no NYSOH Bronze/Iceberg history, reviewed current view, API or MCP surface is accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_ny_nysoh","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["coverage_month","geography_type","geography_value","hios_or_all","measure","source_artifact_sha256","unit"],"backing_store":"logical_not_ingested"},{"source_id":"vt_vhc_data_surfaces","source_fqn":"vt_vhc_data_surfaces","title":"Vermont Health Connect plan, rate, quality and OE overview surfaces","domain":"commercial","stage":"silver","status":"planned","grain":"One immutable source-native PDF within a Vermont plan-design/rate, QHP satisfaction or Open Enrollment overview family.","description":"Eight distributed official pages resolve to 18 exact PDFs for PY2022-PY2026; the current direct site does not expose a granular enrollment-result history.","identity_key":"source_id,source_artifact_sha256,source_family,publisher_period","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: exact PDF bytes are profiled, but no Vermont-direct physical history or semantic table is accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_vt_vhc","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["publisher_period","source_artifact_sha256","source_family"],"backing_store":"logical_not_ingested"},{"source_id":"ar_aid_marketplace_surfaces","source_fqn":"ar_aid_marketplace_surfaces","title":"Arkansas Insurance Department Marketplace application surfaces","domain":"commercial","stage":"silver","status":"blocked","grain":"One candidate enrollment, rate, benefit or template artifact/application result under a publisher-native release identity.","description":"Five exact application surfaces identify 13 public candidates, but current artifact requests reset and the identified archive body is unreachable from this environment.","identity_key":"source_id,canonical_source_url,source_artifact_sha256","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Blocked: landing evidence exists, but no artifact body or source-native observation is accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_ar_aid","dataset_assignment_basis":"source_id_prefix","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["canonical_source_url","source_artifact_sha256"],"backing_store":"logical_not_ingested"},{"source_id":"hix_state_artifact_history","source_fqn":"medicare_silver.hix_state_artifact_revision_history","title":"State Marketplace content-addressed artifact history","domain":"provenance","stage":"registry","status":"planned","grain":"One source and logical-release revision at an exact content SHA, with separate source-native observation and reviewed-pointer histories.","description":"Common Bronze-first physical-history contract for heterogeneous state Marketplace PDFs, workbooks, JSON feeds and dashboard exports; the exact first candidate plan contains 367 occurrences and 366 unique source bodies.","identity_key":"source_id,release_key,content_sha256","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: local PyIceberg proof passes, but production history/control tables have not been created.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_hix_state","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"registry","purpose":"provenance","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["content_sha256","release_key"],"backing_store":"glue"},{"source_id":"hix_identity_bridge","source_fqn":"medicare_silver.dim_hix_temporal_identity_bridge","title":"Marketplace temporal issuer, plan, parent and geography bridge","domain":"commercial","stage":"dim","status":"planned","grain":"One reviewed dated mapping from a source-native issuer, plan or geography key to one canonical key.","description":"Separates HIOS issuer, product, 14-character base-plan, 17-character variant, dated parent ownership and geography identities; overlapping winners fail closed.","identity_key":"mapping_type,source_id,source_key,valid_from,valid_to,canonical_key","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: parser and candidate profile exist, but zero production bridge rows or parent mappings are accepted.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_hix_identity","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"dimension","entity_keys":[],"entity_key_columns":{},"technical_keys":["source_id"],"unmapped_key_tokens":["canonical_key","mapping_type","source_key","valid_from","valid_to"],"backing_store":"glue"},{"source_id":"hix_analytical_marts","source_fqn":"medicare_gold.mart_hix_*","title":"Marketplace analytical mart family","domain":"commercial","stage":"mart","status":"planned","grain":"One source-qualified row at the declared grain of one of seven landscape, affordability, benefit, enrollment, quality, economics or continuity marts.","description":"Seven governed mart contracts with mandatory artifact/snapshot provenance and four independent coverage scores; the first no-write enrollment candidate has 1,581 CA/NJ/NY/WA rows.","identity_key":"mart_id plus the mart-specific declared grain","row_count":null,"last_updated":"2026-09-02","raw_queryable_via":"Not queryable: no production mart or coverage sidecar exists and every API/MCP surface is disabled.","notes":null,"superseded_by":null,"tools":[],"dataset_id":"ds_hix_analytical","dataset_assignment_basis":"source_id_prefix","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["declared","grain","mart-specific","mart_id","plus","the"],"backing_store":"glue"},{"source_id":"cms_fact_pfs_gpci_locality","source_fqn":"medicare_silver.fact_pfs_gpci_locality","title":"CMS PFS Geographic Practice Cost Indices by locality, every RVU release CY2017-2026, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per source row of one RVU release's GPCI file (calendar_year x MAC/carrier x locality); natural key (release_label, row_seq); partitioned by release_label.","description":"The GPCI member of each CMS PFS RVU release ZIP (RVU17D..RVU26C) re-collected through the provenance envelope on 2026-09-07: work_gpci, pe_gpci, mp_gpci as published, with state, carrier_number, locality_number, locality_name. CY2003-2016 (the dual-carrier era, where (calendar_year, state, locality_number) is not unique) is loadable at source grain with --include-gated-gpci and is not loaded by default. Succeeds medicare_gpci_locality (one CY2025 RDS snapshot).","identity_key":"locality_number","row_count":1111,"last_updated":"2026-09-07","freshness_sla":"Annual (PFS final rule, calendar year); refresh after each RVU release.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the release's calendar year; pin it (and release_label) when comparing releases (named 2026-09-07).","One release ZIP is one release_label partition; a reload of one release never touches another."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_pfs_gpci_locality","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"pipelines/medicare/ingest/pfs_locality_runner.py (job build_medicare_pfs_locality) from the RVU release ZIPs; bronze medicare/bronze/cms_pfs_relative_value_files/; RDS registry medicare_source_registry_cache (cms_pfs_relative_value_files#locality_gpci)","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["Localities are CMS payment localities, not counties; join via fact_pfs_locality_config (Counties text) or cms_zip5_locality (ZIP).","CY2003-CY2016 GPCI is not loaded by default (dual-carrier era; source-native key includes carrier_number); CY2000-CY2002 have no live publisher file.","Join on (calendar_year, state, locality_number) WHERE is_current; the 1.0 work-GPCI floor is applied by the publisher in the file."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_pfs_relative_value_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["locality_number"],"backing_store":"glue"},{"source_id":"cms_fact_pfs_locality_config","source_fqn":"medicare_silver.fact_pfs_locality_config","title":"CMS PFS locality configuration (LOCCO), every RVU release CY2003-2026, stamped","domain":"medicare","stage":"silver","status":"live","grain":"One row per source row of one RVU release's LOCCO file (calendar_year x MAC/carrier x locality x official Counties text) after exact duplicate source rows are dropped; natural key (release_label, row_seq).","description":"The LOCCO member of each CMS PFS RVU release ZIP (RVU03D..RVU26C) re-collected through the provenance envelope on 2026-09-07: state, state_name, carrier_number, locality_number, locality_name (fee schedule area) and the publisher's Counties text. It maps county groups to Medicare payment localities and MACs per year; it is NOT a county-FIPS crosswalk (LOCCO publishes text, not FIPS). Succeeds medicare_county_to_locality (one CY2025 RDS snapshot).","identity_key":"state_locality_counties_year","row_count":2381,"last_updated":"2026-09-07","freshness_sla":"Annual; refresh after each RVU release.","recollection":{"cadence":"annual","watermark_field":"calendar_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["watermark_field 'calendar_year' is the release's calendar year; pin it (and release_label) when comparing releases (named 2026-09-07).","One release ZIP is one release_label partition; a reload of one release never touches another."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_silver.fact_pfs_locality_config","commercial_terms":"Public CMS data; freely redistributable.","provenance_chain_ref":"pipelines/medicare/ingest/pfs_locality_runner.py (job build_medicare_pfs_locality) from the RVU release ZIPs; bronze medicare/bronze/cms_pfs_relative_value_files/; RDS registry medicare_source_registry_cache (cms_pfs_relative_value_files#locality_gpci)","context_doc_path":"docs/context_library/medicare/medicare_pfs_ipps_localization.md","known_gaps":["county_name is the publisher's Counties text (e.g. ALL COUNTIES, or a slash-separated list); no FIPS codes. Use cms_zip5_locality for ZIP-level locality resolution.","Pre-2003 files are not served by CMS (current index starts at RVU03)."],"notes":null,"superseded_by":null,"tools":[],"dataset_id":"cms_pfs_relative_value_files","dataset_assignment_basis":"source_register","layer":"silver","asset_type":"table","purpose":"source_data","entity_keys":[],"entity_key_columns":{},"technical_keys":[],"unmapped_key_tokens":["state_locality_counties_year"],"backing_store":"glue"},{"source_id":"vlada_plan_value_national","source_fqn":"medicare_semantic.vw_plan_value_national","title":"Vlada Plan Value, national basis (formerly BenVAT) per contract x plan x segment x county x benefit year","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per benefit_design_year x contract x plan x segment x county_ssa (measured 2026-09-17 in Athena, 9,948,020 rows = 9,948,020 distinct keys, Athena e9083b2e; CY2023-CY2026). Real types (double / int / boolean / varchar); no cast is needed or wanted.","description":"Vlada Plan Value v1, national basis (run d06cf1bf7, signed 2026-08-27; typed rebuild 2026-09-17 verified cell-for-cell against the signed CSVs): total plan value PMPM with _low/_high bounds and grade, medical value beyond Medicare, supplemental expected plan expense, Part B giveback and Part C/D premiums, the net totals, and the D-SNP split. Modeled from the PBP, Landscape, ratebook and enrollment sources; never a CMS figure and never a paid claim. Adds `snp_type` in the county view's labels (none / i_snp / d_snp / c_snp; the CMS code kept as `snp_type_cms_code`) and `is_valued`. Owner source: register w3 vlada_w3_benvat (door RAW, locked by Ben 2026-09-03). Supersedes medicare_semantic.benvat_v1_plan_county, whose 41 string columns read positionally out of CSV.","identity_key":"contract,plan,segment,county_ssa,benefit_design_year","row_count":9948020,"last_updated":"2026-09-17","freshness_sla":"Annual (rebuilt when the PBP / Landscape year lands); the valuation run is signed (d06cf1bf7, 2026-08-27).","recollection":{"cadence":"annual","watermark_field":"benefit_design_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Pin benefit_design_year; giveback and premiums are separate columns, net values are the v1_total_*_net_* fields.","A rerun that moves a published value needs a fresh signature from Ben before it is promoted (the August signatures cover run d06cf1bf7 only)."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_plan_value_national","provenance_chain_ref":"Vlada Plan Value v1 run d06cf1bf7 over cms_ma_pbp + cms_ma_landscape + cms_ma_ratebook + cms_ma_monthly_enrollment (register w3 vlada_w3_benvat); typed rebuild ops/scripts/plan_value_tables_rebuild.py over the signed deliverables in _deliverables/benvat/v1/ (baseline rebuild-manifest.json); Glue view over s3://vlada-platform-raw/medicare_semantic/plan_value_national_v1","known_gaps":["Every value is MODELED, never a filed benefit and never a paid claim; label it modeled and quote the _low/_high bounds for a single plan.","MOST ROWS CARRY NO VALUE (measured 2026-09-17, Athena aa269aee): v1_total_plan_value_pmpm is non-null on 462,513 of 9,948,020 rows (4.6%). Filter `is_valued` before any average. On the retired string table the same count returned 9,948,020 because 9,485,507 of those cells were the empty string, so an unvalued cell looked like a value.","Part C premium is BLANK for design years 2023 and 2024 (measured 2026-09-17, Athena 69493d95: part_c_premium_pmpm non-null on 123 of 2,546,162 rows in 2023 and 0 of 2,554,521 in 2024; populated 2025-2026). Source it from medicare_silver.fact_ma_landscape for those years. F5 / F6 in the post-signature audit.","The four D-SNP lens columns are EMPTY in every year: dsnp_beneficiary_value_pmpm, dsnp_plan_liability_pmpm, dsnp_state_transfer_pmpm and part_d_member_financial_value_at_lis_pmpm are 0 non-null in all four years (measured 2026-09-17, Athena 69493d95). The inputs were not supplied to the signed build (2026 receipt: dsnp_attributes: not supplied); a typed copy of an empty column is an empty column.","v1_total_grade is 'F' on every one of the 9,948,020 rows (measured 2026-09-17, Athena 69493d95) and therefore carries no information. It is F because the weakest load-bearing leg sets the total. Do not present it to a reader. F9 in the post-signature audit.","A filed copay RANGE is valued at its MINIMUM, which is CMS's own out-of-pocket-cost convention (_MC_MIN). 32% of general enrollment (1,011 plans, 6,776,572 members) files the specialist copay as a range with a mean gap of $42, so a plan filing \"$0 to $45\" is valued near a true $0 plan. Disclose the convention and bound it. F10 in the audit.","Segment premiums are not read: 100 of 3,692 valued 2026 plan-segments in 31 contracts carry one premium for all segments where CMS publishes one per segment (78 understated, mean difference -$6.90). Only the premium leg and the net-of-premium totals are affected. F6 in the audit.","Rows that are not valued carry is_valued = false; on the county-basis view the parallel flag is refusal_reason (empty string on every row today). Exclude them before aggregating.","No row-level provenance columns (no source_url / sha256); trace is upstream lineage to the four W3 sources, the signed run id d06cf1bf7 and the rebuild manifest."],"notes":"Name: Ben chose \"Vlada Plan Value\" on 2026-09-17. \"BenVAT\" survives in the source id, the code and the retired table names until a rename lane changes them.","superseded_by":null,"tools":[],"dataset_id":"vlada_w3_benvat","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["county_ssa"]},"technical_keys":[],"unmapped_key_tokens":["benefit_design_year","contract","plan","segment"],"backing_store":"glue"},{"source_id":"vlada_plan_value_county","source_fqn":"medicare_semantic.vw_plan_value_county","title":"Vlada Plan Value, county basis (formerly BenVAT) with per-benefit values and real county enrollment","domain":"medicare","stage":"semantic_view","status":"live","grain":"One row per benefit_design_year x contract x plan x segment x county_ssa (measured 2026-09-17 in Athena, 445,771 rows = 445,771 distinct keys, Athena efc66d87; 844 contracts, CY2023-CY2026). Real types (double / int / boolean / varchar); no cast is needed or wanted.","description":"Vlada Plan Value county basis (run d06cf1bf7, signed 2026-08-27; typed rebuild 2026-09-17 verified cell-for-cell against the signed CSVs): the plan value re-priced and re-utilized per county (v_b) against the national value (v_national), decomposed into price_effect, util_effect and interaction, with the reference and plan PMPM, MOOP relief, the rake diagnostics and the 35 per-benefit-code value columns (v_by_code_*). Adds real county enrollment from the CMS February file with its suppression flag and bounds, the count of a plan's segments in the county, and `snp_type` as labels. Modeled; never a CMS figure. Owner source: register w3 vlada_w3_benvat (door RAW, locked by Ben 2026-09-03). Supersedes medicare_semantic.benvat_county_v1, which read CSV positionally and so mis-named 26 columns for 2023 and 2024.","identity_key":"contract,plan,segment,county_ssa,benefit_design_year","row_count":445771,"last_updated":"2026-09-17","freshness_sla":"Annual (rebuilt with the plan value run); the county basis run is signed (d06cf1bf7, 2026-08-27).","recollection":{"cadence":"annual","watermark_field":"benefit_design_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Pin benefit_design_year; one run per year, the newest signed run replaces the prior.","A rerun that moves a published value needs a fresh signature from Ben before it is promoted."]},"raw_queryable_via":"Athena (read-only via query_substrate): medicare_semantic.vw_plan_value_county","provenance_chain_ref":"Vlada Plan Value county basis run d06cf1bf7 over the national-basis table + cms_ma_ratebook + cms_ma_monthly_enrollment (register w3 vlada_w3_benvat); typed rebuild ops/scripts/plan_value_tables_rebuild.py over the signed deliverables (baseline rebuild-manifest.json); Glue view over s3://vlada-platform-raw/medicare_semantic/plan_value_county_v1 joined to medicare_silver.enrollment_monthly_county","known_gaps":["Every value is MODELED, never a filed benefit and never a paid claim; label it modeled.","WEIGHT BY county_enrollment_feb for any county-weighted figure. It is the plan's real February enrollment in that county (CMS monthly file). NULL means CMS suppressed the cell at under 11 members (151,885 of 445,771 rows) or the cell had no match in the February file (189 rows), measured 2026-09-17 (Athena fc6cedff); county_enrollment_lower_bound / _upper_bound sit beside it. Never read a null as zero.","plan_enrollment_feb_per_segment_proxy is NOT a county weight: it is the PLAN's February enrollment divided by its segment count, the same number on every county row of that plan. Summing it over counties multiplies the market (measured: the old column summed to 848M against 35.7M real members). It is kept only so a pre-swap query can be reproduced. F3 in the post-signature audit.","A NULL v_by_code_<code> means that benefit category was NOT PRICED for that plan, and its value is absent from the total: the reader refused the category and the code drops a refused category from both sides. 26% of 2026 general-enrollment plans (956 of 3,651) lack at least one category, and nothing else on the row says so. F8 in the audit.","v_by_code_16a exists only from design year 2025 (measured 2026-09-17, Athena 1e9a07df: 0 non-null in 2023 and 2024, 116,055 and 124,930 in 2025 and 2026). The category did not exist before 2025, so zero is the right answer, not a gap.","A filed copay RANGE is valued at its MINIMUM, CMS's own out-of-pocket-cost convention (_MC_MIN). 32% of general enrollment files the specialist copay as a range with a mean gap of $42. Disclose it and bound it. F10 in the audit.","refusal_reason is the EMPTY STRING on all 445,771 rows today, never null (measured 2026-09-17, Athena fc6cedff): exclude with refusal_reason = '', not IS NOT NULL. The column is the contract for future runs.","v_b minus v_national is the county adjustment; rake_converged / rake_max_rel_gap and identity_gap are diagnostics, not values.","No plan has two segments in one county (max segments_of_plan_in_county = 1, measured 2026-09-17): county enrollment is never double counted across segments.","No row-level provenance columns; trace is upstream lineage to the national-basis view, the signed run id d06cf1bf7 and the rebuild manifest."],"notes":"Name: Ben chose \"Vlada Plan Value\" on 2026-09-17. \"BenVAT\" survives in the source id, the code and the retired table names until a rename lane changes them.","superseded_by":null,"tools":[],"dataset_id":"vlada_w3_benvat","dataset_assignment_basis":"source_register","layer":"semantic","asset_type":"view","purpose":"serving","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["county_ssa"]},"technical_keys":[],"unmapped_key_tokens":["benefit_design_year","contract","plan","segment"],"backing_store":"glue"},{"source_id":"vlada_benvat_v1_plan_county","source_fqn":"medicare_semantic.benvat_v1_plan_county","title":"BenVAT v1 plan value per contract x plan x segment x county x benefit year (Vlada's modeled benefit valuation)","domain":"medicare","stage":"mart","status":"retired","grain":"One row per benefit_design_year x contract x plan x segment x county_ssa (measured 2026-09-10 in Athena, 9,948,020 rows = 9,948,020 distinct keys; 1,107 contracts, 10,890 plan-segments, CY2023-CY2026). All 41 columns are strings; cast before arithmetic.","description":"Vlada BenVAT v1 output (county basis run d06cf1bf7, signed 2026-08-27): total plan value PMPM with _low/_high bounds and grade, medical value beyond Medicare, supplemental expected plan expense, Part B giveback and Part C/D premiums, the net totals, and the D-SNP split (beneficiary value, plan liability, state transfer). Modeled from the PBP, Landscape, ratebook and enrollment sources; never a CMS figure or a paid claim. Owner source: register w3 vlada_w3_benvat (door RAW, locked by Ben 2026-09-03). Catalog card added 2026-09-10: the table was in the register and in Glue but absent from data_sources.yaml, so discovery pruned it and query_substrate refused it.","identity_key":"contract,plan,segment,county_ssa,benefit_design_year","row_count":9948020,"last_updated":"2026-08-27","freshness_sla":"Annual (rebuilt when the PBP / Landscape year lands); the county basis run is signed (d06cf1bf7, 2026-08-27).","recollection":{"cadence":"annual","watermark_field":"benefit_design_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Pin benefit_design_year; giveback and premiums are separate columns, net values are the v1_total_*_net_* fields."]},"raw_queryable_via":"RETIRED: refused by query_substrate. Use medicare_semantic.vw_plan_value_national.","provenance_chain_ref":"BenVAT v1 county basis run d06cf1bf7 over cms_ma_pbp + cms_ma_landscape + cms_ma_ratebook + cms_ma_monthly_enrollment (register w3 vlada_w3_benvat); Glue external table at s3://vlada-platform-raw/medicare_semantic/benvat_v1_plan_county","known_gaps":["RETIRED 2026-09-17. The DATA was the signed data (every yearly file's sha256 matched the signed receipt), but the table over it read CSV positionally and typed every column as a string. Superseded by medicare_semantic.vw_plan_value_national. The S3 prefix is kept; rollback is re-pointing the register.","Why it is retired: all 41 columns are strings, so an unvalued cell is the empty string and count() reported a value on every one of the 9,948,020 rows (measured 2026-09-17, Athena e997143d: 9,485,507 empty strings against 462,513 real values on the successor). Its snp_type is the raw CMS code ('' / 1 / 3 / 4) while the county table used labels, so a filter copied between the two returned zero rows (F4).","Modeled value, never a filed benefit or a paid claim; label it modeled and quote the _low/_high bounds for a single plan.","Rows are county cells; weight by real county enrollment (county_enrollment_feb on the successor's county-basis view) for a plan-, contract- or parent-level figure.","No row-level provenance columns (no source_url / sha256); trace is upstream lineage to the four W3 sources and the signed run id.","The register data points' keys omitted `contract` until 2026-09-10; `plan` alone (e.g. '801') is shared by hundreds of contracts."],"notes":null,"superseded_by":"medicare_semantic.vw_plan_value_national (typed rebuild 2026-09-17, verified cell-for-cell against the signed deliverables: real doubles instead of 41 string columns, one column layout for every year, one SNP coding, and real NULLs where the CSV carried the empty string)","tools":[],"dataset_id":"vlada_w3_benvat","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["county_ssa"]},"technical_keys":[],"unmapped_key_tokens":["benefit_design_year","contract","plan","segment"],"backing_store":"glue"},{"source_id":"vlada_benvat_county_v1","source_fqn":"medicare_semantic.benvat_county_v1","title":"BenVAT county basis (v_B vs national) per contract x plan x segment x county x benefit year, with refusal reasons","domain":"medicare","stage":"mart","status":"retired","grain":"One row per benefit_design_year x contract x plan x segment x county_ssa (measured 2026-09-10 in Athena, 445,771 rows = 445,771 distinct keys; 844 contracts, 8,275 plan-segments, CY2023-CY2026; 0 rows carry a refusal_reason today). All 71 columns are strings; cast before arithmetic.","description":"Vlada BenVAT county basis output (run d06cf1bf7, signed 2026-08-27): the plan value re-priced and re-utilized per county (v_b) against the national value (v_national), decomposed into price_effect, util_effect and interaction, with the reference and plan PMPM, MOOP relief, the enrollment rake diagnostics and the per-benefit-code value columns (v_by_code_*). Modeled; never a CMS figure. Owner source: register w3 vlada_w3_benvat (door RAW, locked by Ben 2026-09-03). Catalog card added 2026-09-10 for the same reason as benvat_v1_plan_county.","identity_key":"contract,plan,segment,county_ssa,benefit_design_year","row_count":445771,"last_updated":"2026-08-27","freshness_sla":"Annual (rebuilt with the plan value run); the county basis run is signed (d06cf1bf7, 2026-08-27).","recollection":{"cadence":"annual","watermark_field":"benefit_design_year","freshness_threshold":null,"expected_delta":null,"stale_behavior":null,"caveats":["Pin benefit_design_year; one run per year, the newest signed run replaces the prior."]},"raw_queryable_via":"RETIRED: refused by query_substrate. Use medicare_semantic.vw_plan_value_county.","provenance_chain_ref":"BenVAT county basis run d06cf1bf7 over benvat_v1_plan_county + cms_ma_ratebook + cms_ma_monthly_enrollment (register w3 vlada_w3_benvat); Glue external table at s3://vlada-platform-raw/medicare_semantic/benvat_county_v1","known_gaps":["RETIRED 2026-09-17. The DATA was the signed data (each yearly file's sha256 matched the signed receipt), but the table over it read CSV BY POSITION and the 2023 and 2024 files have 70 columns where 2025 and 2026 have 71: v_by_code_16a sits at position 45, not at the end, so for 2023 and 2024 every per-benefit column from 16a through 9b held its right-hand neighbour's value and v_by_code_9b was empty on all 204,786 rows. 2023 mean inpatient read $0.02 where the signed value is $5.31. Superseded by medicare_semantic.vw_plan_value_county. The S3 prefix is kept; rollback is re-pointing the register. F1 in the post-signature audit.","Also why it is retired: all 71 columns are strings (F2), and the only enrollment column was the plan total repeated on every county row while the card told callers to weight by it (F3; it summed to 848M against 35.7M real members).","Exclude rows with a non-empty refusal_reason before averaging (none today; the column is the contract for future runs).","v_b minus v_national is the county adjustment; rake_converged / rake_max_rel_gap are diagnostics, not values.","No row-level provenance columns; trace is upstream lineage to the plan value table and the signed run id."],"notes":null,"superseded_by":"medicare_semantic.vw_plan_value_county (typed rebuild 2026-09-17, verified cell-for-cell against the signed deliverables: real doubles instead of 71 string columns, one column layout for every year so the 2023 and 2024 per-benefit columns are no longer shifted by one, and real county enrollment joined with its suppression bounds)","tools":[],"dataset_id":"vlada_w3_benvat","dataset_assignment_basis":"source_register","layer":"curated","asset_type":"table","purpose":"mart","entity_keys":["ssa:county"],"entity_key_columns":{"ssa:county":["county_ssa"]},"technical_keys":[],"unmapped_key_tokens":["benefit_design_year","contract","plan","segment"],"backing_store":"glue"}],"tools":[{"name":"asp_pricing_lookup","version":"1.0.0","description":"Given an HCPCS code or short-description search, returns Medicare Part B ASP quarterly payment-limit rows from drug_silver.fact_drug_asp_quarterly with trend aggregates. Use for Part B reimbursement checks and CY 2026 IRA/MFP methodology caveats.","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_drug_asp_quarterly#drug_asp","drug_silver.fact_drug_asp_quarterly"],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_asp_quarterly"],"semantic_views_used":[],"known_gaps":["asp_cy_2026_mpfs_ira_mfp_layering","asp_pricing_lookup_no_match","asp_pricing_lookup_truncated"]},{"name":"certified_measure","version":"1.0.0","description":"Run a GOVERNED KPI by name from the certified measures registry. A measure is a registry entry (definition + vintage bindings + official citation + canonical SQL); this tool runs ONLY that registry SQL, so a governed statistic (like the enrollment-weighted share of MA-PD enrollees in 4-plus star contracts) is computed by a compiled methodology, never an improvised join. Call with NO name to list every measure with its status and definition. Call with a name (and optionally rating_year, an int) to execute that measure and get the rows plus the vintage columns, the official citation, the certification status (draft / certified), and the definitional notes. Use this for any governed KPI FIRST; if no measure covers the question, fall back to query_substrate and label the result uncertified.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Runs ONLY the registry's canonical SQL; a governed question with no matching certified measure is NOT answered here, and there is currently NO sanctioned raw-SQL fallback (query_substrate is quarantined pending its truncation-honesty re-grade). An unanswered governed question stays unanswered rather than improvised.","A measure with status 'draft' has not yet been certified by the owner; treat its number as provisional until status is 'certified'."]},{"name":"compare_hospital_rates","version":"1.10.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 -- since 1.6.0 'institutional'/'professional' each WIDEN to include billing_class_resolved='both' rows, a charge posted on both the facility and professional side of a bill per the HPT schema; pass 'institutional_only'/'professional_only' for the strict single-class stratum), 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 the view's canonical payer columns (`payer_canonical_id`, `payer_parent_name`, `payer_entity_class`, `payer_match_method`) plus `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. CHEAPEST HEADLINE (1.2.0): `value.cheapest` is ranked over rows PLAUSIBLE for the code's Medicare basis -- when the allowed amount is a real procedure (>= $500) a row under 0.3x Medicare (the comparability cascade's own lower sane bound) is set aside into `value.implausible_tail` (full rows + floor + reason, never deleted; benchmark still includes it), and the rest rank hospital-stated methodology (fee_schedule/case_rate/per_diem) before methodology-unknown, rate ascending within each tier -- read `plausibility` + `rank_tier` on each row. Under the $500 gate (imaging / visits / labs) no floor applies, so a $44 head CT still headlines. CASE-RATE HEADLINE (1.7.0): on a DRG/case-rate seat the floor is 0.5x (not 0.3x -- an inpatient rate below half of IPPS is not credible as the full case price), and `cheapest` headlines hospital-STATED case_rate rows ONLY when at least one survives the floor; methodology-unknown rows are demoted into `value.implausible_tail` (tail_reason='methodology_unknown_demoted') even when they themselves clear the floor. `cheapest` headlines an unknown row only when NO stated row survives, and a `headline_methodology_unknown` warning caveat says so. ONE CODE SYSTEM PER WINDOW (1.3.0): `cheapest` holds rows of the seated code system only (`value.code_system_resolved`, the dominant system or the caller's `code_system`), each row stamped `code_system`; when the floor empties a full window the tool re-asks once for rows at or above the floor rate (`value.cheapest_window.second_pass`), and if `cheapest` still ends empty a `no_plausible_rows_in_window` caveat says why. ONE METHODOLOGY FAMILY PER WINDOW (1.4.0): within the seated code system, `cheapest` and the re-seated `value.benchmark` / `comparable_benchmark` are further restricted to ONE methodology family -- fee_schedule (a line, the natural family for CPT/HCPCS/APC/RC), case_rate (an admission, the natural family for a DRG/MS-DRG seat), or per_diem (a day) -- because a case rate, a per diem and a fee schedule price different economic objects and must never share a median or a ranked list. `methodology_family` (optional: fee_schedule|case_rate|per_diem) overrides the natural seat. Rows the hospital stated in a DIFFERENT family are set aside into `value.other_family`, in full, never blended in; `value.by_methodology_family` reports n/n_hospitals/p10/median/p90 for every family present, and a `methodology_families_mixed` caveat fires when more than 10% of the population sits outside the seated family. BY_METHODOLOGY RECONCILES (1.6.1): `value.by_methodology` (percent_of_charge/fee_schedule/case_rate/per_diem/other/unknown, with median_rate_over_gross_charge) is narrowed to the SAME population `value.benchmark.n` reports -- sum(by_methodology[].n) == benchmark.n, ALWAYS, by construction; the unstratified, every-family view (within the seated code system) is `value.by_methodology_all_families`, which is what `value.percent_of_charge_share` and the `methodology_mix` caveat read (percent_of_charge rows are always 'unknown' family and would otherwise be invisible once a family is seated). 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 ~80.9% of volume and line-of-business ~85.7% (measured on the 70553 probe, 2026-08-13; call coverage_status for live counts), unmatched rates fall to '(unresolved)'/'unspecified'; bare Blue-family labels (e.g. 'Bcbs') are bucketed '(blue family: label too generic to attribute)' with payer_resolution='generic_label' and never attributed to a specific Blue parent; 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. DRG GROUPER PRECISION (1.5.0): MS-DRG, APR-DRG and AP-DRG are different maintainers with different numbering (MS-DRG 470 = joint replacement, APR-DRG 470 = chronic kidney disease) and only MS-DRG prices against the IPPS base; the served mart still collapses all of them into one bare 'DRG' code system, so `value.medicare.precision` reads 'drg_grouper_unknown' (with a warning caveat) on that seat until the code_system_resolved bucket split rebuild lands, and 'exact' otherwise. BOTH-CLASS DEFAULT STRATUM (1.6.0): billing_class 'institutional'/'professional' each widen to include billing_class_resolved='both' rows (a charge the HPT schema posts for both sides of a bill); every row still carries its own resolved `billing_class`, and a `both_class_rows_included` caveat states the measured count whenever the answer includes at least one such row. Measured on CT (2026-08-18): 9.63% of REAL_NEGOTIATED rows are 'both', 100% with no institutional sibling row -- previously invisible at the old strict-institutional default. Pass 'institutional_only'/'professional_only' for the pre-1.6.0 strict single-class stratum.","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":"coverage_status","version":"1.1.0","description":"DEPRECATED 2026-09-14 (one deprecation window): for 'what data does Vlada have?' call find_data_sources -- the one discovery door, whose inventory this tool now reports verbatim in `inventory`. What is kept here for the window is the LIVE section counts nothing else serves. The single LIVE answer to 'what data does Vlada have?'. Replaces the conflicting coverage numbers scattered across tool docs with one endpoint whose every figure is computed live, read from an authoritative catalog metadata surface, or deferred to submit_query when it needs a heavy scan, never hardcoded. Sections (default all): `hospital` (distinct CCNs with chargemaster rows, distinct CCNs with negotiated_dollar rows, total fact rows), `commercial` (served payers live from the canonical-graph engine registry — the payers the resolution engine can serve — plus the canonical semantic-registry count), `resolution` (payer_canonical_id non-null % and line_of_business specified % on a bounded state+code probe), and `freshness` (latest recorded vintage per source family). Every section carries computed_at + a method string; every number carries a definition string so there is exactly one meaning per figure. Request-path queries are partition- bounded under a ~10s budget; anything heavier is returned as available_via: submit_query. Pass allow_heavy_scan=true to compute the distinct-CCN tiers inline (deploy-time / off-request-path use).","layer":"L2","domain":"hospital","data_sources":["vlada_curated.vw_fact_hospital_chargemaster_current","vlada_curated.vw_fact_hospital_chargemaster_canonical"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_fact_hospital_chargemaster_current","vlada_curated.vw_fact_hospital_chargemaster_canonical"],"semantic_views_used":["vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_fact_hospital_chargemaster_current"],"known_gaps":["distinct-CCN tiers are DEFERRED to submit_query by default because the hospital fact is partitioned by (hospital_state, version_id), not hospital_ccn; pass allow_heavy_scan=true to compute them inline.","total_fact_rows is a catalog metadata estimate (may lag the live table after a reingest); it is NOT a live COUNT(*).","resolution percentages are scoped to a single bounded probe (state + billing code), returned in `probe`, not the whole substrate.","freshness dates are catalog-recorded vintages, not live watermark reads.","served_payers counts BUILT canonical-graph serving indexes (the engine registry); a build's presence does not by itself certify every downstream table surface (catalog / provenance tiers gate that)."]},{"name":"describe_data_source","version":"1.3.0","description":"Return the catalog record for one substrate data source. Compact by default (grain, queryable, claim ceiling, freshness SLA, top caveats, recommended next action, columns); pass verbosity='full' for the previous full record: description, row count, provenance chain reference, context doc path, known gaps, and the full source_product_card. IDENTIFIERS: accepts the PUBLIC source_code that find_data_sources returns (e.g. cms_ma_plan_payment) as well as a table FQN (e.g. vlada_curated.fact_rate) or a catalog source_id -- all three resolve to the same card. Also accepts a data-point ID, returning its exact bound table plus the selected point's units, grain, nulls and execution route. When the card includes a coverage-check recipe, run its stated query to inspect retained editions; it is not measured coverage. Do not infer all-history coverage from current-only rows. Avoid extra schema calls when this card already supplies the needed columns. A RETIRED source answers with a redirect (status retired + superseded_by + the successor's fqn), never a card. COLUMNS (1.1.0): the card's `columns` field lists each column's name and type (and a one-line note where the source publishes one), read from a committed snapshot -- never a live Glue call -- so a caller no longer has to `SELECT * LIMIT n` on query_substrate just to learn a table's shape. A source not yet in the snapshot reads `columns_unavailable: run snapshot` rather than silently omitting the field; run ops/scripts/snapshot_catalog_columns.py to populate it. WHAT TO QUERY (2026-09-18): every card carries a block saying what to type. It states the literal fully-qualified table name the raw SQL door accepts -- neither the public source code nor the catalog source id is a table -- plus the predicates a correct read carries (a currentness filter, a year pin, a partition column), and one bounded example SELECT that has been run through the door's own SQL guard before it was printed. A source served by a typed tool instead names that tool and its call; a seat not entitled to the table is told which pack grants it. Column lists are split: the data columns first, the row-lineage columns every row carries in their own named group.","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: marts, columns, invariants, canonical payers, and the tools YOU can call (the same list tools/list returns for you, never a wider catalog). Compact by default (a manifest: marts + a name + one-line summary per tool, under ~8K chars). Fetch one section with describe_schema(section='<mart>') / section='tools' / section='invariants'. Pass verbosity='full' for the previous full payload. Agents call this first to learn the surface, then fetch the section or tool they need.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"excluded_prescriber_payment_screen","version":"1.2.0","description":"Given an NPI (10-digit), returns OIG LEIE exclusion status and — if excluded — any Open Payments received OR Part D prescribing activity recorded AFTER the exclusion date (and before any reinstatement). The textbook qui-tam / False Claims Act screening query. Bridges three substrate sources: dim_oig_leie (LEIE), fact_drug_payment_to_prescriber (Open Payments), fact_part_d_prescriber (Part D Prescriber-by-Drug).\n\nReturns: total post-exclusion payment dollars + Part D drug-cost exposure, broken down by year + top 5 manufacturers. Every answer carries an explicit exclusion_status (not_in_leie, excluded, or excluded_then_reinstated) beside the dollars, so a $0 result is never ambiguous: a not-in-LEIE NPI returns zero ANCHORED to the LEIE snapshot date it was checked against (leie_asserted_at), which is a different thing from an excluded prescriber who drew no post-exclusion payments.\n\nKNOWN GAPS: open_payments_publication_lag_one_year (current PY publishes June+1); part_d_puf_annual_grain_only (Part D PUF is annual not monthly — finer-grain timing requires claims data). LEIE refreshes monthly per the M-6 schedule (cycle 2).","layer":"L2","domain":"drug","data_sources":["drug_silver.dim_oig_leie","drug_silver.fact_drug_payment_to_prescriber","drug_silver.fact_part_d_prescriber"],"underlying_silver_tables_for_pinning":["drug_silver.dim_oig_leie","drug_silver.fact_drug_payment_to_prescriber","drug_silver.fact_part_d_prescriber"],"semantic_views_used":[],"known_gaps":["open_payments_publication_lag_one_year","part_d_puf_annual_grain_only"]},{"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. Compact by default (identity + queryable + claim ceiling + the exact describe_data_source call per hit); pass verbosity='full' for the previous full source_product_card per result. Paginates with limit (default 25, max 200) + offset; the response carries total_count, returned_count, and offset. Optional filters: {domain, stage, status, limit}. Agents call this first to discover what data Vlada has. Since 2026-09-02 the answer leads with DATA POINTS (`data_points`: the measure/dimension asked for, with its source, door, table.column and must-read trap) and the table cards follow as physical locations. Every hit carries `source_code` -- the one public code, which describe_data_source accepts verbatim -- alongside the table's `source_fqn`. Points and tables are ranked by ONE ranker (the authored data-point scorer). Retired tables are never returned; they appear only as `supersedes` on the live successor's card. BOUNDED (2026-09-18): the default call is compact and paged -- both the table cards and the data points come back a page at a time, each with its own total and next offset -- so a default call can never truncate. Pass verbosity='full' for the whole point record and the full source_product_card per hit.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"formulary_churn","version":"1.0.0","description":"Given a quarter-pair (report_quarter_from, report_quarter_to) AND a formulary or plan filter, returns the formulary delta: drugs added, drugs dropped, drugs re-tiered, and optionally drugs whose control flags (prior auth / step therapy / quantity limit) changed. Diffs drug_silver.fact_drug_formulary across two SPUF report_quarters on (formulary_id, ndc11) keys.\n\nReturns: per-category row lists (cap 5000 each), aggregates (formularies_compared, n_added, n_dropped, n_tier_changed, n_control_changed, n_unchanged, churn_rate, tier_movement_distribution), truncated_by_category flags.\n\nREADING churn_rate: it is (added + dropped + re-tiered) divided by the number of drugs on the formulary in the FROM quarter — CHANGE EVENTS PER FROM-QUARTER DRUG, not a percentage. It is >= 0 and CAN EXCEED 1 (a formulary that drops everything and adds as many new drugs scores 2.0), because added drugs are not members of the denominator. The answer carries churn_rate_definition saying exactly this, the two denominators (n_in_from_quarter, n_in_to_quarter), and two bounded companions that ARE 0-1: share_dropped (dropped / FROM-quarter drugs) and share_added (added / TO-quarter drugs).\n\nUse cases: year-over-year formulary stability tracking, drop investigations for a specific drug class, IRA-era churn rate (crossing 2025 → 2026 will surface the redesign-driven churn).\n\nKNOWN GAPS: spuf_quarterly_publication_lag (CMS publishes 6 weeks after quarter end; very recent quarter changes won't show); ira_era_break_2026 (IRA Part D redesign in 2026 changed formulary structures; churn comparison crossing this boundary mixes regime changes with normal churn); formulary_churn_truncated (per-category lists capped at 5000).","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_drug_formulary","drug_silver.dim_part_d_plan"],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_formulary","drug_silver.dim_part_d_plan"],"semantic_views_used":[],"known_gaps":["spuf_quarterly_publication_lag","ira_era_break_2026","formulary_churn_truncated","formulary_churn_no_match"]},{"name":"get_drug_source_inventory","version":"1.0.0","description":"Discover the drug substrate. Returns one row per drug_silver table (and per expected-but-missing source) with: domain, row_type, row count, time range, refresh cadence, next expected refresh, MCP tool(s) exposing the table, quality signals (dup_pk groups + null_bronze count + last quality-check outcome), cadence-drift and agent-usage signals, and the current Iceberg snapshot id reader at last inventory refresh.\n\nFilters: domain (spuf / drug_identity / regulatory / etc.), row_type (existing | expected_missing | deprecated | blocked_restricted), refresh_cadence, has_mcp_tool (bool — true=only MCP-exposed, false=dark-zone), quality_failing_only (bool), production_only (bool, default true), table_name (exact match), expected_source_id (filter negative-space rows).\n\nThis is the meta-tool for substrate discovery. Call FIRST to plan which other tools to call, to detect stale tables before relying on them, OR to find sources the substrate doesn't yet have (negative-space awareness via row_type='expected_missing' — a v2 addition over MA's v1).\n\nv2 additions over MA's get_ma_source_inventory: per-row quality signals (closes blind spot: existence ≠ correctness), snapshot pinning columns (closes blind spot: inventory ≠ current state), and negative-space rows for sources we expect but haven't ingested yet. v3 additions: cadence drift and trailing 7-day agent query counts.\n\nSOURCE: drug_silver.dim_drug_source_inventory — refreshed daily.","layer":"L2","domain":"drug","data_sources":[],"underlying_silver_tables_for_pinning":["drug_silver.dim_drug_source_inventory"],"semantic_views_used":[],"known_gaps":["drug_inventory_quality_check_stale"]},{"name":"get_enrollment","version":"0.2.0","description":"Returns CMS monthly enrollment for a Medicare Advantage plan or contract: the member count, the trend over time, and, at contract level, the MA-only vs Part-D split, plus org/parent and plan type. Filter by contract_id (required) + optional plan_id (plan grain vs contract total), and optional year ('2024') or month ('2024-03'); with neither, returns the latest month plus a trailing 13-month trend. Monthly coverage back to 2006. Every row carries the year-over-year change (yoy_change / yoy_pct) vs the same month one year earlier; plan rows carry the plan's SNP class (snp_type) when applicable.\n\nRETURNS a detail payload, not a bare count: value.summary (latest_month, latest_enrollment, yoy_change / yoy_pct, ma_only_count / part_d_count, trend min/max and change over the window), value.months (the per-month trend rows), value.row_counts (matched / returned / truncated / limit) and value.query (the filters actually applied). `limit` bounds the trend rows returned (default 13 months, max 2000); a truncated list always carries a caveat.\n\nEnrollment is the SPINE every other MA metric joins to (per-member, share-weighted). SUPPRESSION is honest: CMS redacts cells under 11 enrollees, which come back as count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell', never a zero, and the suppression caveat fires only when a returned month is actually redacted. A contract id that does not exist returns found=false with a not_found_reason, never a suppression story.\n\nPair with get_plan_payment / get_mlr / get_pbp_benefit to weight or normalize by members. SOURCE: CMS Monthly Enrollment by Plan / by Contract.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.enrollment_monthly_plan","medicare_silver.monthly_contract_enrollment_summary"],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_plan","medicare_silver.monthly_contract_enrollment_summary"],"semantic_views_used":[],"known_gaps":["Cells under 11 enrollees are CMS-redacted: count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell'.","MA-only vs Part-D split is contract-level only (omit plan_id to get it).","County / market-share grain lives in enrollment_monthly_county (612M rows); this tool serves plan + contract totals."]},{"name":"get_exchange_plan_profile","version":"1.0.0","description":"One ACA Marketplace (healthcare.gov / HIX) plan's profile for a plan year, every field tagged with the CCIIO PUF it came from. Give plan_id (the 14-character HIOS standard component id, e.g. 38344AK1060001) for the plan: issuer, metal level, plan type (HMO/PPO/EPO/POS), Individual vs SHOP, on/off exchange, network, county footprint, premium benchmarks at age 21/40/60 (min across the plan's rating areas, plus the age-40 max), the per-age premium curve from the Rate PUF (include_rate_curve, default true), headline cost shares (PCP / specialist / ER / urgent care / generic drug copay, inpatient coinsurance), CMS quality stars, and the issuer's individual-market MLR. Or give state (+ optional plan_year, metal_level, issuer_id, plan_type, on_off_exchange) for the bounded list of that state's plans, cheapest age-40 premium first. plan_year defaults to the latest year held (PY2014-2026). Deductible / MOOP are returned as not_available (not in the composed profile). FFM states only: a state-based marketplace (CA, NY, PA, GA, ...) is absent at source and the tool says so rather than returning nothing silently.","layer":"L2","domain":"commercial","data_sources":["medicare_silver.fact_exchange_plan_profile","medicare_silver.fact_rate_puf"],"underlying_silver_tables_for_pinning":["medicare_silver.fact_exchange_plan_profile","medicare_silver.fact_rate_puf"],"semantic_views_used":[],"known_gaps":["FFM (healthcare.gov) states only; state-based marketplaces are absent at source.","Deductible / MOOP are not in the composed profile (untyped raw JSON in the Plan Attributes PUF today) and are returned as not_available.","premium_age21/40/60 are the MIN across the plan's rating areas (age-40 MAX also given); county-grain premium needs the rating area (use rate_curve / the Rate PUF).","Cost shares are the base variant (-01) as filed; CSR variants differ. Quality only for CMS-rated plans in PY2023/2024/2026; MLR only PY2019-2024; PY2015 premiums thin at source; medical plans only (v1)."]},{"name":"get_hos","version":"0.2.0","description":"Returns a Medicare Advantage contract's CMS Health Outcomes Survey (HOS) rates across the four survey topics (fall_risk_management, urinary_incontinence, osteoporosis_testing, physical_activity), each with the two reported rates and the year-over-year change. Filter by contract_id (required) + optional year (defaults to the latest; report years 2019-2025).\n\nRETURNS a detail payload, not a topic count: value.topics is the per-topic row list (topic, report_year, rate1, rate2, rate3, rate1_yoy), value.summary rolls it up (topic_count, which topics reported, the highest and lowest rate1), value.row_counts carries matched / returned / truncated and value.query the filters applied. `limit` bounds the rows (default 200, max 2000).\n\nHOS is the beneficiary-survey companion to the chart-abstracted HEDIS rates and feeds several Part C Star measures. rate1/rate2 are the survey's two published rates for the topic (e.g. the share who reported the issue and the share who discussed it with a provider); see the CMS HOS documentation for exact definitions. Pair with get_stars. A contract id with no HOS rows returns found=false with a not_found_reason.\n\nSOURCE: CMS Health Outcomes Survey (HOS) Public Use File.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.hedis_hos_frm","medicare_silver.hedis_hos_mui","medicare_silver.hedis_hos_oto","medicare_silver.hedis_hos_pao"],"underlying_silver_tables_for_pinning":["medicare_silver.hedis_hos_frm","medicare_silver.hedis_hos_mui","medicare_silver.hedis_hos_oto","medicare_silver.hedis_hos_pao"],"semantic_views_used":[],"known_gaps":["rate1/rate2 semantics are topic-specific; consult the CMS HOS documentation."]},{"name":"get_hospital_quality","version":"0.1.0","description":"Returns one hospital's CMS Care Compare quality record by CCN: the overall star rating (1-5) with hospital type / ownership; every Care Compare measure for the hospital (mortality and complication rates, unplanned readmission / ED-return rates, timely and effective care, healthcare-associated infections SIRs, outpatient imaging efficiency, maternal health) with the score, CMS's compared-to-national verdict where published, denominator, confidence bounds and measurement window; the HCAHPS patient-experience summary (summary star + per-dimension star ratings and linear mean scores) for the latest reporting year the hospital has; and the HRRP excess readmission ratios per condition for the latest fiscal year (ratio > 1 = more readmissions than nationally expected). Inputs: ccn (required, 6-char CMS certification number); optional measure_group (alias: measure_source) to get ONE group's measure rows (complications_deaths | unplanned_visits | timely_care | healthcare_assoc_infections | outpatient_imaging_efficiency | maternal_health); optional limit and offset to page the measure rows (default limit 25 once detail is asked for).\n\nTHE DEFAULT CALL IS A SUMMARY: ccn alone returns the overall rating, the HCAHPS and HRRP blocks, and the measure GROUPS with a count each (summary.measure_groups: measure_count / available / not_available / vs_national per group) — NOT the ~108 measure rows, which exceed the response budget for a single hospital. Totals are still reported (summary.measure_count) and row_counts.measures names what was withheld; ask again with measure_group, or limit / offset, for the rows.\n\nRETURNS a detail payload: value.summary (facility, overall_rating with status + footnote, hcahps_summary_star, counts, measure_groups, measure_detail_mode, and a `blocks` map saying which of overall_rating / measures / hcahps / hrrp are available for THIS hospital); value.measures, value.hcahps, value.hrrp row lists. Every row carries status = available | not_available (with the CMS footnote or reason), source_table and source_vintage (asserted_at). Nothing is fabricated: a suppressed or unreported measure is not_available, never a zero; an unrated hospital reports overall_rating null with the CMS footnote. All four sources are read WHERE is_current = true. An unknown CCN returns found=false.\n\nSOURCE: CMS Provider Data Catalog (Care Compare) Hospital General Information, hospital measure files, HCAHPS, and the HRRP hospital file.","layer":"L2","domain":"hospital","data_sources":["medicare_silver.dim_hospital_quality","medicare_silver.fact_hospital_quality_measure","medicare_silver.fact_hcahps","medicare_silver.fact_hrrp"],"underlying_silver_tables_for_pinning":["medicare_silver.dim_hospital_quality","medicare_silver.fact_hospital_quality_measure","medicare_silver.fact_hcahps","medicare_silver.fact_hrrp"],"semantic_views_used":[],"known_gaps":["overall_rating is null for hospitals CMS does not rate (~40% of CCNs) — unrated, not 0.","score_numeric is null for suppressed / categorical / footnoted measures; the row is returned as not_available with the footnote.","HCAHPS answer-percent distribution rows are not returned (star + linear mean summary only); HRRP is the latest fiscal year only.","Measure semantics differ per measure_id; do not compare scores across unlike measures."]},{"name":"get_landscape","version":"0.2.0","description":"Returns the CMS Landscape view of a Medicare plan: monthly consolidated premium, in-network MOOP, overall star rating, plan type, and the county/state service-area breadth. Filter by contract_id (required) + optional plan_id and year; omit plan_id to list all plans on a contract.\n\nRETURNS a detail payload, not a plan-year count: value.plans is the actual PLAN LIST (report_year, plan_id, plan_name, org_name, plan_type, category, consolidated_premium, part_c_premium, part_d_premium, moop_in_network, overall_star_rating, service_area_county_count / state_count), sorted premium ascending so the cheapest plans lead; value.summary rolls it up (plan_count, premium min / median / max, zero-premium count, star min / max, total distinct counties); value.row_counts carries matched / returned / truncated and value.query the filters applied. `limit` bounds the plan list (default 200, max 2000); a truncated list always carries a caveat.\n\nCovers ALL plan categories (MA, PDP, SNP, MMP, Cost), 2007-2026. The Landscape drops ~early September, ahead of the October benefits drop, so it is the first official view of the upcoming plan year. Pair with get_pbp_benefit (benefits) for the full picture. A contract / plan / year with no Landscape rows returns found=false with a not_found_reason.\n\nSOURCE: CMS MA/Part-D Landscape source files.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.fact_ma_landscape"],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape"],"semantic_views_used":[],"known_gaps":[]},{"name":"get_market_share","version":"0.2.0","description":"Returns a Medicare Advantage plan's or contract's county-level enrollment and its SHARE of the local MA market: for each county, the plan's enrollees, the county's total MA enrolled and Medicare-eligible population, the MA penetration rate, the plan's share of county MA enrollment, and the year-over-year change in the plan's county enrollment. Filter by contract_id (required) + optional plan_id (plan vs contract total), optional state (2-letter, e.g. 'FL'), and optional month ('2024-03'); defaults to the latest available month.\n\nRETURNS an actual SHARE with the arithmetic disclosed, not a raw headcount: value.summary.share_pct is the footprint share, and it always ships alongside its numerator (share_numerator_plan_enrollees) and its denominator (share_denominator_county_ma_enrolled), so nobody has to trust a bare percentage. The denominator is the total MA enrollment of the counties this plan actually operates in for the month in scope, NOT the national MA market. value.counties is the per-county row list (plan enrollees, county MA enrolled, county eligibles, penetration, share_pct, yoy_change), largest first; value.row_counts carries matched / returned / truncated and value.query the resolved month. `limit` bounds the county list (default 200, max 2000).\n\nThis is the geography + competition lens; pair with get_enrollment for the plan/contract totals. Suppressed county cells (CMS redacts under 11) come back with null enrollees and null share, never zero, and the summary carries a [low, high] bound on the numerator that brackets them. A contract id with no county rows returns found=false with a not_found_reason.\n\nSOURCE: CMS Monthly Enrollment by CPSC + MA State/County Penetration.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.enrollment_monthly_county","medicare_silver.ma_state_county_penetration"],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_county","medicare_silver.ma_state_county_penetration"],"semantic_views_used":[],"known_gaps":["County cells under 11 enrollees are CMS-redacted (null enrollees, null share).","Share = plan county enrollees / total MA enrolled in county (penetration file)."]},{"name":"get_medicaid_mco_enrollment","version":"0.1.0","description":"Returns Medicaid managed-care enrollment for ONE state: the annual CMS 'Enrollment by Program and Plan' roster (each managed-care program x plan with SEPARATE Medicaid-only, dual and total member counts and a value_status per count, plus parent organization) for the requested or latest calendar year (2016-2024); the state's TOTAL Medicaid and CHIP enrollment from the CMS monthly state report for the latest 12 reporting months (context: all delivery systems, managed care and fee-for-service, CHIP separate); and, for the four T-MSIS dashboard pilot states (AZ, MI, NV, NM), the MCO roster with county footprint and service categories; and the state's OWN monthly plan-level publication for its latest month (45 jurisdictions). Inputs: state (required, 2-letter USPS code); optional year (plan-roster calendar year, defaults to the latest the state has); optional limit.\n\nRETURNS a detail payload: value.summary (state, plan_year, plan_count, program_count, the SOURCE-PUBLISHED sum of plan total_enrollment where reported_numeric for the comprehensive_medical benefit scope ONLY, plus per-benefit-scope sums that must never be added together, with the count of rows that are suppressed / not reported, the latest monthly total Medicaid+CHIP / Medicaid / CHIP enrollment with its reporting_period, and a `blocks` map saying which sources have rows for this state); value.plans (one row per program x plan x region: benefit_scope (comprehensive_medical, behavioral_health, dental, pharmacy, ltss, pace, nemt, pccm, limited_benefit, unknown) with the rule that set it, medicaid_only / dual / total each with value + value_status, parent_organization, calendar_year, source_table); value.monthly (reporting_period, total_medicaid_and_chip_enrollment, total_medicaid_enrollment, total_chip_enrollment, adult / child enrollment, revision + final flags, source_table); value.mco_roster (mco_name, plan_category, county_count, service_categories, source_table; NO enrollment number); value.monthly_plans (the state-published plan rows for the latest monthly observation_period, statewide where the state publishes statewide rows, otherwise sub-state as published, each with reported_value, value_unit, value_status, row_role and source_url; never summed into a state total). Every number carries its as-of period and exact source table. Nothing is recomputed or reconciled across sources: Medicaid-only + dual is not re-summed, a published 0 is reported_zero_or_suppressed (never exact zero), and the annual plan roster is a different population and grain from the monthly state total. All sources are read WHERE is_current = true (monthly: is_latest_revision = true). An unknown state returns found=false.\n\nSOURCE: CMS/Data.Medicaid.gov Medicaid Managed Care Enrollment by Program and Plan (state-reported, annual); CMS Medicaid & CHIP Application, Eligibility and Enrollment monthly state report; CMS Medicaid MCO Dashboard (T-MSIS, four pilot states); state Medicaid agencies' monthly managed-care enrollment reports (medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v2).","layer":"L2","domain":"medicare","data_sources":["medicare_silver.cms_medicaid_managed_care_plan_enrollment","medicare_silver.cms_medicaid_chip_enrollment_monthly_state","medicare_silver.fact_medicaid_managed_care"],"underlying_silver_tables_for_pinning":["medicare_silver.cms_medicaid_managed_care_plan_enrollment","medicare_silver.cms_medicaid_chip_enrollment_monthly_state","medicare_silver.fact_medicaid_managed_care"],"semantic_views_used":[],"known_gaps":["Plan roster is annual (2016-2024) and state-reported; plan labels and parent organizations are publisher text, not stable payer identities.","Published 0 may be exact zero or CMS confidentiality suppression under ten (reported_zero_or_suppressed) — never asserted as exact zero.","Monthly series = TOTAL Medicaid and CHIP enrollment (all delivery systems), not managed-care enrollment; CHIP is a separate column and is not inside the plan-level counts.","fact_medicaid_managed_care covers four pilot states (AZ, MI, NV, NM) and carries utilization, not enrollment; returned as a roster only."]},{"name":"get_negotiated_rate","version":"2.1.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. Near-zero dollar rates (positive, under $1 — the ghost class the benchmark path excludes) are never picked over a plausible rate; if one is all that matched, it is served flagged is_ghost_candidate at confidence 0.2 with a caveat, never as a real price.","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_pbp_benefit","version":"0.3.0","description":"Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.).\n\nPolymorphic — pass `category` to route to the right semantic view. All categories share the standard envelope: cost_share_string, copay_amount, coinsurance_pct, limit_text, auth_required, referral_required, network_type, max_oop_applies + category-specific extension fields (e.g., dental_sub_benefit).\n\nRequired: contract_id, plan_id, payment_year, category. The category must be one of the 19 supported (call get_pbp_benefit_catalog to list).\n\nThe response `value` is the full benefit-detail object: `rows` (every matched benefit row, with cost sharing, limits, and category extension fields), `row_count`, the resolved `category`/`human_label`/`view_fqn`, the `audit_chain` (CMS source URL + sha256 per row), and a `summary` sub-field carrying the single-row headline cost_share_string (or the row count when multiple sub-benefit rows match) for a quick read. Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+). Cross-year queries get cross-shift caveats.\n\nLive categories auto-discovered from contract registry — call get_pbp_benefit_catalog to enumerate at runtime. As of 2026-05-25 the 19 onboarded categories are: dental, vision, hearing, otc, moop, transportation, b19_combined_package, inpatient_hospital, emergency_urgent, health_professionals, outpatient_hospital, partb_rx_drugs, snf, home_health, dme, renal_dialysis, supplemental_other, section_c_pos_oon, partd_drugs.\n\nA contract/plan/year/category combination with NO rows is REFUSED with code NO_DATA, not answered with an empty complete: the refusal states what was searched and routes to get_landscape (the plan ids that really exist for that contract and year) and get_pbp_benefit_catalog (the categories). One view is read, so a nonexistent plan and a plan with nothing in this category cannot be told apart here; the refusal says so.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.fact_ma_landscape","medicare_silver.pbp_mrx","medicare_silver.pbp_mrx_tier","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_b13_other_services","medicare_silver.pbp_section_b14_preventive","medicare_silver.pbp_section_b15_partb_rx_drugs","medicare_silver.pbp_section_b16_dental","medicare_silver.pbp_section_b17_eye_exams_wear","medicare_silver.pbp_section_b18_hearing_exams_aids","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_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_oon","medicare_silver.pbp_section_c_pos","medicare_silver.pbp_section_d","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"],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape","medicare_silver.pbp_mrx","medicare_silver.pbp_mrx_tier","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_b13_other_services","medicare_silver.pbp_section_b14_preventive","medicare_silver.pbp_section_b15_partb_rx_drugs","medicare_silver.pbp_section_b16_dental","medicare_silver.pbp_section_b17_eye_exams_wear","medicare_silver.pbp_section_b18_hearing_exams_aids","medicare_silver.pbp_section_b19a_model_test_vbid_uf","medicare_silver.pbp_section_b19b_model_test_vbid_uf","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_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_oon","medicare_silver.pbp_section_c_pos","medicare_silver.pbp_section_d"],"semantic_views_used":["medicare_semantic.vw_pbp_ambulance","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_combined_supplemental","medicare_semantic.vw_pbp_dental","medicare_semantic.vw_pbp_dme","medicare_semantic.vw_pbp_dsnp_cost_share","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_meals","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_plan_deductible","medicare_semantic.vw_pbp_plan_premium","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"],"known_gaps":["PBP-PK-PRE-2010","PBP-QUARTERLY-PRE-2018"]},{"name":"get_stars","version":"0.2.0","description":"Returns a Medicare Advantage contract's CMS Star Ratings: the Overall, Part C, and Part D summary stars for a rating year, each with the year-over-year change vs the prior year. Set include_measures=true to also get the full per-measure breakdown (measure name, part, domain, weight, the raw value and its star, and the star's YoY change) so you can see exactly which measures moved the rating. Filter by contract_id (required) + optional year (the rating_year, defaults to the latest) + optional limit (max measure rows returned). Rating years 2012-2026. The answer is a detail payload: the headline stars sit in value.summary, the part rows in value.summary_parts, the measure rows in value.measures.\n\nStars drive the quality-bonus payment and rebate, so this sits directly upstream of get_plan_payment / get_mlr (the economics) and is reported at the CONTRACT level (no plan_id).\n\nSOURCE: CMS Star Ratings (summary + measure-level + measure dimension).","layer":"L2","domain":"medicare","data_sources":["medicare_silver.stars_ratings_summary","medicare_silver.stars_ratings_measure","medicare_silver.dim_stars_measures"],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_summary","medicare_silver.stars_ratings_measure","medicare_silver.dim_stars_measures"],"semantic_views_used":[],"known_gaps":["Stars are contract-level (no plan_id).","Measure set + weights are methodology-versioned per rating_year; a measure retired or added between years has no YoY counterpart (null change)."]},{"name":"get_stars_cutpoints","version":"0.1.0","description":"Returns CMS-published per-measure star-level cutpoints (threshold boundaries) for a rating_year. Optional filters: measure_id, org_subtype (MA-PD | PDP | ALL), star_level (1-5).\n\nmeasure_id is matched on ONE id space: pass 'C09' or 'C09:' — some stored ids carry a trailing colon and both forms return the same rows; returned measure_id values never carry the colon.\n\nUse cases: 'what's the 4-star line for measure C09?'; 'show me cutpoint drift year-over-year'; 'how much would contract H1234 need to improve to reach 5 stars on measure D08?'.\n\nSOURCE: CMS Tech Notes Attachment H (Tukey-aware threshold tables) for RY2024+, Attachment H pre-Tukey for RY2017-RY2023, pre-fixed cutpoints for RY2015-RY2016 (predetermined 4-star thresholds; clustering not yet universal).\n\nCLEAN DATA: backing table follows the silver supersession contract — exactly one row per natural key. Phase 6a inventory verified 1.0× dup factor post-6c migration.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.stars_cutpoints"],"underlying_silver_tables_for_pinning":["medicare_silver.stars_cutpoints"],"semantic_views_used":[],"known_gaps":["stars_methodology_pdf_uncited"]},{"name":"how_to_join","version":"1.3.0","description":"Return the fail-closed measured way to join two Vlada substrate tables, including an explicit DIRECT_OK, DIRECT_DECLARED_KEY, NEEDS_GRAIN, ROUTE_THROUGH_DIM, ROUTE_MULTIHOP, or DO_NOT_SERVE directive. Direct joins come from (in order) the measured connection registry, the VALIDATED join graph (catalog.json join_edges: uniqueness >= 0.999 and match >= 0.80, measured live), or the semantic layer's declared shared surrogate key (DIRECT_DECLARED_KEY, labelled not-live-measured); a validated or declared direct join is always preferred over a route and never refused. Route coverage (min_coverage) is the weaker side of the weakest hop; a route under 50% is labelled low_coverage_route. Unproved composite, NEEDS_GRAIN, quarantined, impossible, or N:M direct evidence cannot be served. With only table_a, it lists every executable connection from that table.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Only joins resolvable to physical columns + measurable live are in the registry; big-fact joins are dimension-routed. Absence of a verified join means 'not proven', not 'impossible'."]},{"name":"ira_drug_label_risk_screen","version":"1.0.0","description":"Given an optional drug_name (brand or generic substring), returns IRA-Selected Drugs with their CURRENT FDA structured-label posture (boxed warning / REMS / pregnancy / pediatric flags) and most-recent Drugs@FDA approval activity. When drug_name is omitted, screens ALL drugs in fact_drug_reimbursement.\n\nThe wedge: drugs with active boxed warning + REMS carry FDA-acknowledged safety signals that weaken the manufacturer's MFP-defense argument during CMS negotiation. Hedge funds track this for negotiated-rate directional signal; pharma market access uses it to brief the negotiation team; plaintiff bar uses it to weight cross-substrate exposure.\n\nSubstrate joins: fact_drug_reimbursement (IRA list) × dim_drug_label (shipped 2026-05-16, SPL summary) × dim_drug_application (shipped 2026-05-16, Drugs@FDA approval history).\n\nReference demo (MEASURED 2026-08-01): ELIQUIS -> 22 current label revisions, boxed warning YES, REMS no, pregnancy warning YES, risk_signal_count 2. Across the whole IRA cohort: 25 drugs screened, 14 carry a boxed warning, 0 carry a REMS.\n\nKNOWN GAPS: ira_drug_name_to_label_fuzzy_match (drug_name match is case-insensitive substring on brand_name OR generic_name — no robust ingredient resolver yet). manufacturer_to_sponsor_fuzzy_match (IRA manufacturer field matched against dim_drug_application.sponsor_name via substring — same name can appear in multiple corporate forms).","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_drug_reimbursement#ira_mfp","drug_silver.dim_drug_label","drug_silver.dim_drug_application"],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_reimbursement","drug_silver.dim_drug_label","drug_silver.dim_drug_application"],"semantic_views_used":[],"known_gaps":["ira_drug_name_to_label_fuzzy_match","manufacturer_to_sponsor_fuzzy_match"]},{"name":"ira_mfp_exposure","version":"1.0.0","description":"Returns the cross-payer federal exposure for an IRA-eligible drug: IRA Maximum Fair Price (when in the IPAY-2026 cohort) + Part D total spend + Part B total spend + Medicaid SDUD total spend, anchored to a specific data year. Reference demos, MEASURED 2026-08-01 against live Athena: STELARA DY2023 = Part D $2,987,778,599.90 + Part B $27,614,584.61 + Medicaid SDUD $3,302,074,349.03 = $6,317,467,533.54 combined, IRA MFP $4,695.00/dose CY2026. ELIQUIS DY2023 = Part D $18,273,451,967.00 + Medicaid SDUD $2,233,903,339.92 = $20,507,355,306.92 combined, IRA MFP $237.25/dose CY2026. (This description previously read 'Stelara ... = $20.5B'. $20.5B is real but it is ELIQUIS; Stelara is $6.32B. The label was on the wrong drug, which is why the tool looked ~3x low against its own demo.)\n\nSOURCE COVERAGE: IRA MFP (fact_drug_reimbursement) covers 10 IPAY-2026 drugs only; queries outside that cohort return ira_mfp_unit_price_usd=null with a coverage_gap caveat (federal-payor spend is still answered). Part D + Part B PUFs publish annually. Medicaid SDUD has per-cell suppression (suppression_used=true rows excluded from totals with a suppression_warning caveat).\n\nALIAS RESOLUTION: M-6 parent_alias + FDA dim_drug fallback applied to drug_name — brand inputs (Stelara) resolve to generic (ustekinumab) and vice-versa. Aliases used are surfaced in the response envelope.\n\nKNOWN PUBLICATION GAPS: see gap_registry entries ira_mfp_partial_cohort_ipay_2026, medicaid_sdud_suppression_used_flag, part_d_puf_annual_grain_only.","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_drug_reimbursement#ira_mfp","drug_silver.fact_drug_spending_part_d","drug_silver.fact_drug_spending_part_b","drug_silver.fact_drug_medicaid_utilization","drug_silver.dim_drug"],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_reimbursement","drug_silver.fact_drug_spending_part_d","drug_silver.fact_drug_spending_part_b","drug_silver.fact_drug_medicaid_utilization","drug_silver.dim_drug"],"semantic_views_used":[],"known_gaps":["ira_mfp_partial_cohort_ipay_2026","medicaid_sdud_suppression_used_flag","part_d_puf_annual_grain_only"]},{"name":"lookup_rates_for_npi","version":"1.1.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. PAGED: `limit` (default 25, max 500) and `offset` bound both `matching_rates` and `provider_groups`; `rate_count` / `provider_group_count` are the full totals and `paging` names what was cut plus the call that returns the next page. `value` is a COUNT, never a price: it is the TOTAL number of matching rates, `unit` says so, and `headline` spells it out in fields (kind=count, is_a_price=false). The prices themselves are one per row in `matching_rates`.","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.1.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. PAGED: `limit` (default 25, max 500) and `offset` bound both `matching_rates` and `provider_groups`; `rate_count` / `provider_group_count` are the full totals and `paging` names what was cut plus the call that returns the next page. `value` is a COUNT, never a price: it is the TOTAL number of matching rates, `unit` says so, and `headline` spells it out in fields (kind=count, is_a_price=false). The prices themselves are one per row in `matching_rates`.","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":"medicare_allowed","version":"0.1.0","description":"Returns the Medicare allowed amount for ONE billing code (CPT/HCPCS, or an MS-DRG for inpatient) from every Medicare fee schedule that prices it: PFS (professional, national non-facility), OPPS Addendum B (hospital outpatient APC), ASC, CLFS (lab), and IPPS (national DRG amount). Inputs: billing_code (required); optional care_class to pick the setting that fits a site (02_asc, 03_outpatient, 04_urgent_care, 05_imaging, 06_lab, 07_dialysis — the same preference table care_site_price uses for its Medicare floor); optional setting to return one schedule only (PFS_non_facility | OPPS_APC | ASC | CLFS | IPPS_MSDRG_national); optional medicare_year to PIN a schedule vintage (4-digit year; omit it and the LATEST edition held for the chosen schedule is served — an older vintage is never returned unless you pin it); optional limit.\n\nRETURNS a detail payload: value.medicare_year and value.setting state the vintage and schedule actually served; value.summary carries the PREFERRED row for the requested care_class (medicare_allowed, medicare_source, medicare_year, billing_class), the latest year held per schedule (latest_year_by_schedule) and whether the year was pinned or resolved (medicare_year_selection), plus the count of schedules that price the code; value.settings lists EVERY schedule row for the code with what it is (fee_schedule, professional vs facility component, site, national basis, locality_adjusted=false, source_table, medicare_year vintage). Every number is NATIONAL — no GPCI / wage-index localisation is applied, and PFS is the NON-FACILITY (office) professional rate. A code priced on no schedule returns found=false ('not priced on these Medicare schedules', never $0). Reads the latest available edition per schedule (vlada_curated.vw_medicare_benchmark; the underlying M-2 fact tables are read WHERE is_current).\n\nSOURCE: CMS PFS RVU + conversion factor, OPPS Addendum B, ASC addendum, CLFS, IPPS Table 5 + base rates.","layer":"L2","domain":"medicare","data_sources":["vlada_curated.vw_medicare_benchmark","medicare_silver.fact_pfs_rvu","medicare_silver.fact_opps_addendum_b","medicare_silver.fact_asc_addendum","medicare_silver.fact_clfs_national_rate"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_medicare_benchmark","medicare_silver.fact_pfs_rvu","medicare_silver.fact_opps_addendum_b","medicare_silver.fact_asc_addendum","medicare_silver.fact_clfs_national_rate"],"semantic_views_used":[],"known_gaps":["National amounts only: no GPCI (PFS) or wage-index (OPPS/ASC/IPPS) localisation.","PFS is the non-facility (office) professional rate; the facility-setting professional rate is not served.","DMEPOS / anesthesia / ESRD schedules are not loaded; a code absent from every served schedule is 'not priced here', not $0."]},{"name":"pbm_compensation_rollup","version":"2.0.0","description":"Sums Form 5500 Schedule C direct + indirect compensation for a named PBM across one or more plan years. Every aggregate runs SERVER-SIDE in SQL over the whole matching population; the per-provider-name and per-plan-year rows the total is made of ride the answer, and each alias spelling carries its own measured attribution. M-6 alias chain resolves OptumRx -> OPTUMRX + OPTUM RX + Catamaran (post-2015 acquisition), Express Scripts -> ESI / ESI MAIL PHARMACY, CVS Caremark -> all variants; a name that is NOT a registered alias_form says so instead of silently searching one literal string.\n\nReference demo (re-measured live 2026-08-01): OptumRx plan year 2023 -> $1,461,686,909 direct comp across 295 plan-filings and 295 provider rows, attributed OPTUMRX $1,036,556,258 / OPTUM RX $425,110,391 / Catamaran $20,260.","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_form5500_service_provider","drug_silver.fact_form5500_filing"],"underlying_silver_tables_for_pinning":["drug_silver.fact_form5500_service_provider","drug_silver.fact_form5500_filing"],"semantic_views_used":[],"known_gaps":[]},{"name":"plan_commercial_price_proof","version":"1.3.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.3.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.3.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.3.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":"prove_ma_enrollment_trend","version":"0.1.0","description":"Execute a bounded MA enrollment-trend proof. Returns the answer value plus a receipt with substrate, source snapshots, filters, guardrails, caveats, input hash, response hash, and replay pointer. Reads three silver tables (CPSC county, monthly-enrollment-plan, plan-crosswalks) at their published snapshots.","layer":"L2","domain":"medicare","data_sources":["medicare_silver.enrollment_monthly_county","medicare_silver.enrollment_monthly_plan","medicare_silver.plan_crosswalks_annual","medicare_silver.monthly_contract_enrollment_summary"],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_county","medicare_silver.enrollment_monthly_plan","medicare_silver.plan_crosswalks_annual","medicare_silver.monthly_contract_enrollment_summary"],"semantic_views_used":[],"known_gaps":[]},{"name":"query","version":"0.3.0","description":"SAFE STUB. Given a catalog source FQN, return HOW to query it FROM THIS MCP -- and only paths executable here: query_substrate (sync, small) or submit_query -> poll_query -> fetch_query (async), each with the source's fqn and one working example SELECT carrying an explicit LIMIT (and WHERE is_current when the table is M-2 versioned). Never executes SQL. A source outside the queryable set (retired / partial / planned / unattributed) gets no executable path and the rule that excluded it. COLUMNS (0.3.0): example_sql names the first ~6 real columns instead of `SELECT *` when the source is in the committed columns snapshot (same one describe_data_source's `columns` field reads); falls back to `SELECT *` when it is not, never a guessed column list. IDENTIFIERS (2026-09-18): this accepts every identifier describe_data_source accepts -- the public source code, a catalog source id, or a table FQN -- and answers with the same what-to-type block, so the two can never disagree about whether an identifier exists.","layer":"L1","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]},{"name":"query_substrate","version":"1.1.0","description":"Set fresh=true for a user-requested saved-view update: execute without the result cache; all access and scan limits still apply. 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 in the queryable set your account is entitled to (others are rejected); M-2 versioned tables must be filtered on is_current (injected for a single-table SELECT, otherwise rejected with the column named); results are LIMIT-bounded (max 10000), the delivered payload is bounded to ~47K chars, and the scan is cost-capped. Any bound that drops rows is reported as truncated:true with rows_returned + rows_dropped/total_rows_estimate and a caveat saying how to get the rest (aggregate in SQL, narrower predicate, ORDER BY + OFFSET paging, or submit_query for a scan that needs more time). 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":"recall_spend_window","version":"2.0.0","description":"Given an FDA-assigned recall_number, returns recall metadata plus Medicare Part D and Medicaid SDUD federal spend on the recalled drug during the recall window (initiation -> termination), summed SERVER-SIDE with per-year Part D rows and per-NDC Medicaid rows riding the answer. The recall source carries NO NDC (openfda_product_ndc_first is NULL on all 17,830 current rows), so the Medicaid leg reaches NDCs through dim_drug on the openFDA product name and says so. Each leg reports its own published-year coverage, so 'no spend', 'not published yet' and 'no join key' are three different answers instead of one null.\n\nMedicaid totals EXCLUDE the SDUD national roll-up, which CMS publishes under state 'XX' beside the 50 state rows and which would otherwise roughly double every Medicaid figure.\n\nReference demo: recall_number D-1489-2019 (Fresenius Kabi fluorouracil, Class I, window 2019-2022) exercises both legs and the NDC bridge. This description quotes NO dollar figure on purpose: the answer is the only place a number lives, so a change to the computation can never leave a stale figure in the documentation. It did once -- the demo totals here were the pre-2026-08-10 national-roll-up double count and stood six weeks after the fix.","layer":"L2","domain":"drug","data_sources":["drug_silver.fact_drug_recall","drug_silver.fact_drug_spending_part_d","drug_silver.fact_drug_medicaid_utilization","drug_silver.dim_drug"],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_recall","drug_silver.fact_drug_spending_part_d","drug_silver.fact_drug_medicaid_utilization","drug_silver.dim_drug"],"semantic_views_used":[],"known_gaps":["medicaid_sdud_suppression_used_flag","part_d_puf_annual_grain_only"]},{"name":"replay_commercial_price_proof","version":"1.3.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.3.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":"resolve_provider","version":"1.0.0","description":"Resolve a provider's identity: an NPI, an EIN, or an organisation name (+ state) -> the Medicare CCN(s) it maps to, the CCN's provider type from the CCN authority (vlada_curated.dim_provider_ccn: 101,528 CCNs across hospitals, SNFs, home health, hospice, FQHC, RHC, ASC, dialysis, IRF, LTCH), the NPPES record, the PECOS Medicare enrollment(s) with organisation name and provider type, and (include_ownership, default true) the PECOS ownership edges — owners, percentage, and the private-equity / REIT / holding-company / chain flags. Every candidate carries its match method, a confidence, and the source table per field. NPI->CCN is resolved by AGREEMENT across two bridges (provider_facility_xref, dim_hospital_external); if they disagree the answer is ambiguous_conflict with both candidates and no resolved CCN, never a guess. An unknown NPI returns unresolved with the reason, not an error. EIN and name resolution reach hospitals only (the estate's EIN-bearing roster); a shared-system EIN lists every CCN as a candidate.","layer":"L2","domain":"provider_identity","data_sources":["vlada_curated.dim_provider_ccn","vlada_curated.dim_provider","vlada_curated.provider_facility_xref","vlada_curated.dim_hospital_external","medicare_silver.fact_pecos_enrollment","medicare_silver.fact_provider_ownership"],"underlying_silver_tables_for_pinning":["vlada_curated.dim_provider_ccn","vlada_curated.dim_provider","vlada_curated.provider_facility_xref","vlada_curated.dim_hospital_external","medicare_silver.fact_pecos_enrollment","medicare_silver.fact_provider_ownership"],"semantic_views_used":[],"known_gaps":["NPI->CCN recall ~87% (bridge union, measured 2026-06 by the employer-book harness); individual NPIs and non-hospital organisations usually resolve to PECOS + NPPES only.","EIN and name resolution reach hospitals (dim_hospital_external) plus PECOS org names; the non-hospital rosters carry no EIN.","provider_type follows the ten CMS rosters in dim_provider_ccn; a provider type we hold no roster for is absent from the authority.","Ownership edges are keyed on PECOS enrollment_id and are self-reported; percentage can be null for indirect interests."]},{"name":"search_tools","version":"1.0.0","description":"DEPRECATED 2026-09-14 (one deprecation window): call find_data_sources instead -- it ranks the DATA POINT you asked for with the served tool that answers it, using the same ranker this tool now adapts. Kept callable so nothing in flight breaks. Find the right tool for a task. Given a natural-language description of what you want to do, returns the best-matching tools ranked by relevance, each as name + one_line_summary + params (compact by default; pass verbose=true for the full descriptions), 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. Paginates with limit (default 25, max 200) + offset. 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_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":"submit_query","version":"1.1.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. Arguments are validated against the target tool's own input model AT ACCEPT TIME, so a malformed submit is refused immediately (reason=invalid_arguments) instead of after you waited for the job. A POINT-LOOKUP CALL IS REFUSED, not queued: the refusal carries the direct call to make instead, with your own arguments already in it. That includes a bounded compare_hospital_rates read (one billing_code + one state), which the precomputed window answers in about a second. Pass force=true only when the SYNC door sent you here (too_large_for_sync, tool_timeout) — that route is always accepted. Poll with poll_query(job_id) and read the result with fetch_query(job_id). A refusal names the async-eligible targets and their current serving state, so you always know what this lane can run today.","layer":"L2","domain":"curated","data_sources":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[]}]}