Add CBO income tax receipts source package

Author: MaxGhenis

arch/source_package.py

@@ -78,6 +78,9 @@
     "cbo-revenue-projections-income-by-source-2026-02": Path(
         "cbo/revenue_projections_income_by_source_2026_02"
     ),
+    "cbo-individual-income-tax-receipts-2026-02": Path(
+        "cbo/individual_income_tax_receipts_2026_02"
+    ),
     "census-acs-s0101-congressional-district-age-2024": Path(
         "census/acs_s0101_district_2024"
     ),

db/data/cbo/individual_income_tax_receipts_2026_02/cbo_individual_income_tax_receipts_2026_02.csv

@@ -0,0 +1,2 @@
+source_concept_id,label,definition_note,year_2021,year_2022,year_2023,year_2024
+individual_income_taxes,Individual income taxes,Federal individual income tax receipts in CBO budget data; dollars,2044000000000,2632146000000,2176481000000,2426067000000

db/data/cbo/individual_income_tax_receipts_2026_02/manifest.yaml

@@ -0,0 +1,23 @@
+source_id: cbo
+package_id: cbo-individual-income-tax-receipts-2026-02
+dataset: cbo_individual_income_tax_receipts_2026_02
+source_page: https://www.cbo.gov/data/budget-economic-data
+table: CBO budget and economic data, individual income tax receipts
+notes: >-
+  Curated Arch extract of CBO federal individual income tax receipts from the
+  February 2026 Historical Budget Data workbook. Values mirror the CBO receipts
+  series used by PolicyEngine-US calibration parameters and are stored as a
+  source-backed Ledger package for Populace fiscal targeting.
+files:
+  2026:
+    filename: cbo_individual_income_tax_receipts_2026_02.csv
+    source_url: https://www.cbo.gov/system/files/2026-02/51134-2026-02-Historical-Budget-Data.xlsx
+    source_table: CBO budget and economic data, individual income tax receipts
+    sha256: 9cd016b7b3ed0c9602b8ad9f75f859c13e2636fb7c2e16a678b388b0fd17aeea
+    size_bytes: 251
+    storage:
+      r2:
+        provider: r2
+        bucket: arch-raw
+        key: raw/cbo/cbo-individual-income-tax-receipts-2026-02/2026/9cd016b7b3ed0c9602b8ad9f75f859c13e2636fb7c2e16a678b388b0fd17aeea/cbo_individual_income_tax_receipts_2026_02.csv
+        uri: r2://arch-raw/raw/cbo/cbo-individual-income-tax-receipts-2026-02/2026/9cd016b7b3ed0c9602b8ad9f75f859c13e2636fb7c2e16a678b388b0fd17aeea/cbo_individual_income_tax_receipts_2026_02.csv

packages/cbo/individual_income_tax_receipts_2026_02/source_package.yaml

@@ -0,0 +1,74 @@
+schema_version: arch.source_package.v1
+package_id: cbo-individual-income-tax-receipts-2026-02
+label: CBO federal individual income tax receipts
+artifact:
+  source_name: cbo
+  source_table: CBO budget and economic data, individual income tax receipts
+  resource_package: db
+  resource_directory: data/cbo/individual_income_tax_receipts_2026_02
+  manifest: manifest.yaml
+  vintage: cbo_2026_02_budget_projections
+  extracted_at: "2026-06-16"
+  extraction_method: >-
+    curated CSV extract from CBO February 2026 Historical Budget Data workbook.
+    Values mirror CBO individual income tax receipts used in PolicyEngine-US
+    calibration parameters and are stored here as source-backed Ledger facts
+    for Populace fiscal targeting.
+  parser: delimited_text_full_rows
+  sheet_name: income_tax_receipts
+  artifact_year: 2026
+  selected_rows:
+    - source_concept_id: individual_income_taxes
+record_sets:
+  - record_set_id: cbo.fy{year}.revenues
+    record_set_spec_id: cbo.individual_income_tax_receipts.v1
+    source_record_id_prefix: cbo.fy{year}.revenues
+    sheet_name: income_tax_receipts
+    period_type: fiscal_year
+    period: "{year}"
+    geography_id: 0100000US
+    geography_level: country
+    geography_name: United States
+    geography_vintage: current
+    entity: government
+    entity_role: federal_government
+    domain: federal_receipts
+    groupby_dimension: cbo.revenue_source
+    rows:
+      - value_id: individual_income_taxes
+        label: Individual income taxes
+        ordinal: 0
+        row_number: 2
+        table_record_kind: total
+        expected_row_header_column: A
+        expected_row_header: individual_income_taxes
+        guard_cells:
+          - column: B
+            expected_value: Individual income taxes
+            label: CBO row label
+    measures:
+      - measure_id: actual_amount
+        label: CBO individual income tax receipts
+        ordinal: 0
+        column_by_year:
+          2021: D
+          2022: E
+          2023: F
+          2024: G
+        source_column_id: year_{year}
+        expected_column_header_row: 1
+        expected_column_header: year_{year}
+        concept: cbo.individual_income_tax_receipts
+        source_concept: cbo.individual_income_tax_receipts
+        concept_relation: exact
+        concept_authority: cbo
+        concept_evidence_url: https://www.cbo.gov/system/files/2026-02/51134-2026-02-Historical-Budget-Data.xlsx
+        concept_evidence_notes: >-
+          CBO reports federal individual income tax receipts in budget and
+          economic data historical and projection tables. Populace maps this
+          fiscal-year receipts aggregate to its federal income_tax macro
+          calibration control; IRS SOI liability totals are distributional
+          controls and do not replace this row.
+        unit: usd
+        aggregation: sum
+        expected_cell_type: number

tests/test_arch_source_package.py

@@ -489,6 +489,54 @@ def test_cbo_income_by_source_package_preserves_cbo_projection_concepts():
     )
 
 
+def test_cbo_individual_income_tax_receipts_package_builds_fy2024_fact():
+    package = load_source_package("cbo-individual-income-tax-receipts-2026-02")
+    cells = package.build_source_cells(2024)
+    records = package.build_source_records(2024, cells=cells)
+    facts = package.build_facts(2024, cells=cells)
+    consumer_rows = consumer_fact_rows(facts)
+    values_by_record = {fact.source_record_id: fact for fact in facts}
+    expected_record_id = "cbo.fy2024.revenues.individual_income_taxes.actual_amount"
+    expected_sha = "9cd016b7b3ed0c9602b8ad9f75f859c13e2636fb7c2e16a678b388b0fd17aeea"
+    expected_url = (
+        "https://www.cbo.gov/system/files/2026-02/"
+        "51134-2026-02-Historical-Budget-Data.xlsx"
+    )
+    expected_r2_uri = (
+        "r2://arch-raw/raw/cbo/"
+        "cbo-individual-income-tax-receipts-2026-02/2026/"
+        f"{expected_sha}/cbo_individual_income_tax_receipts_2026_02.csv"
+    )
+
+    assert package.package_id == "cbo-individual-income-tax-receipts-2026-02"
+    assert len(cells) == 14
+    assert validate_source_cells(cells).valid
+    assert len(records) == 1
+    assert len(facts) == 1
+    assert validate_facts(facts).valid
+    assert validate_consumer_fact_contract(facts).valid
+    assert len(consumer_rows) == 1
+    assert {record.source_record_id for record in records} == {expected_record_id}
+    assert all(fact.source.source_name == "cbo" for fact in facts)
+    assert {fact.source.source_sha256 for fact in facts} == {expected_sha}
+    assert {fact.source.source_size_bytes for fact in facts} == {251}
+    assert {fact.source.url for fact in facts} == {expected_url}
+    assert {fact.source.raw_r2_uri for fact in facts} == {expected_r2_uri}
+
+    fact = values_by_record[expected_record_id]
+    assert fact.value == 2_426_067_000_000
+    assert fact.period.type == "fiscal_year"
+    assert fact.period.value == 2024
+    assert fact.geography.id == "0100000US"
+    assert fact.entity.name == "government"
+    assert fact.measure.concept == "cbo.individual_income_tax_receipts"
+    assert fact.measure.source_concept == "cbo.individual_income_tax_receipts"
+    assert fact.measure.unit == "usd"
+    assert fact.layout.groupby_value_id == "individual_income_taxes"
+    assert fact.layout.measure_id == "actual_amount"
+    assert consumer_rows[0]["lineage"]["source_record_id"] == expected_record_id
+
+
 def test_validate_source_package_reports_fixture_counts():
     report = validate_source_package("soi-table-1-1", year=2023)