Target-parity contract for populace-us: gate + wire missing SSA SSI families

packages/populace-build/src/populace/build/us/country_package.json

@@ -19,6 +19,8 @@
   "state_spm_poverty_levels.json",
   "support_spine.json",
   "take_up_contract.json",
+  "target_parity_feed_families.json",
+  "target_parity_manifest.json",
   "tax_expenditure_reforms.json"
  ]
 }

packages/populace-build/src/populace/build/us/target_parity_feed_families.json

@@ -0,0 +1,83 @@
+{
+ "feed": "consumer_facts_buildh_v8.jsonl",
+ "feed_sha256": "94b7155f7ca9e2de32ddb3a0add2fff2d8c66e73147fe5bd112cff3ba69b1669",
+ "families": {
+  "bea_nipa.business_current_transfer_receipts": 1,
+  "bea_nipa.defined_contribution_actual_contributions": 1,
+  "bea_nipa.defined_contribution_employer_contributions": 1,
+  "bea_nipa.disposable_personal_income": 1,
+  "bea_nipa.employer_government_social_insurance_contributions": 1,
+  "bea_nipa.employer_pension_and_insurance_contributions": 1,
+  "bea_nipa.farm_proprietors_income": 1,
+  "bea_nipa.government_social_benefits_to_persons": 1,
+  "bea_nipa.medicaid_benefits": 1,
+  "bea_nipa.medicare_benefits": 1,
+  "bea_nipa.nonfarm_proprietors_income": 1,
+  "bea_nipa.other_government_social_benefits": 1,
+  "bea_nipa.personal_current_taxes": 1,
+  "bea_nipa.personal_current_transfer_receipts": 1,
+  "bea_nipa.personal_dividend_income": 1,
+  "bea_nipa.personal_income": 1,
+  "bea_nipa.personal_interest_income": 1,
+  "bea_nipa.personal_outlays": 1,
+  "bea_nipa.personal_saving": 1,
+  "bea_nipa.personal_saving_rate": 1,
+  "bea_nipa.proprietors_income": 1,
+  "bea_nipa.rental_income_of_persons": 1,
+  "bea_nipa.social_security_benefits": 1,
+  "bea_nipa.supplements_to_wages_and_salaries": 1,
+  "bea_nipa.total_wages_salaries": 3,
+  "bea_nipa.unemployment_insurance_benefits": 1,
+  "bea_nipa.veterans_benefits": 1,
+  "bea_regional.state_contributions_for_government_social_insurance": 52,
+  "bea_regional.state_dividends_interest_rent": 52,
+  "bea_regional.state_personal_current_transfer_receipts": 52,
+  "bea_regional.state_personal_income": 52,
+  "bea_regional.state_proprietors_income": 52,
+  "bea_regional.state_residence_adjustment": 52,
+  "bea_regional.state_supplements_to_wages_salaries": 52,
+  "bea_regional.state_wages_salaries": 52,
+  "cbo.revenue_projection": 30,
+  "cbo.revenues": 1,
+  "census.popproj2023": 86,
+  "census_acs.acs1_2023": 468,
+  "census_pep.national_resident_population_age": 19,
+  "census_pep.v2024": 969,
+  "census_stc.individual_income_tax_collections": 46,
+  "cms_aca.oep2024": 153,
+  "cms_medicaid.state_enrollment": 475,
+  "cms_medicare.part_b_premium_income": 1,
+  "cms_nhe.medicaid_title_xix_expenditures": 1,
+  "federal_reserve_z1.households_nonprofits_balance_sheet": 1,
+  "hhs_acf_liheap.national_profile": 2,
+  "hhs_acf_tanf.average_monthly_families": 55,
+  "hhs_acf_tanf.average_monthly_recipients": 3,
+  "hhs_acf_tanf.cash_assistance": 52,
+  "irs_soi.congressional_district_2022": 26880,
+  "irs_soi.filing_season_week47": 34,
+  "irs_soi.form_w2_401k_elective_deferrals": 1,
+  "irs_soi.form_w2_designated_roth_401k_contributions": 1,
+  "irs_soi.form_w2_social_security_tips": 3,
+  "irs_soi.historic_table_2": 5654,
+  "irs_soi.roth_ira_contributions": 2,
+  "irs_soi.state_2022": 4,
+  "irs_soi.table_1_1": 84,
+  "irs_soi.table_1_2": 7,
+  "irs_soi.table_1_4": 557,
+  "irs_soi.table_2_1": 39,
+  "irs_soi.table_2_5": 472,
+  "irs_soi.table_4_3": 18,
+  "irs_soi.traditional_ira_contributions": 2,
+  "jct.tax_expenditures": 5,
+  "kff.marketplace_effectuated_enrollment": 52,
+  "ssa_supplement.oasdi_ssi_payments": 6,
+  "ssa_supplement.ssi_payments": 208,
+  "ssa_supplement.ssi_recipients": 208,
+  "usda_snap.national_average_monthly_households": 1,
+  "usda_snap.national_average_monthly_persons": 2,
+  "usda_snap.national_benefits": 1,
+  "usda_snap.state_average_monthly_households": 53,
+  "usda_snap.state_average_monthly_persons": 106,
+  "usda_snap.state_benefits": 53
+ }
+}

packages/populace-build/src/populace/build/us_runtime/__init__.py

@@ -552,6 +552,21 @@
     us_release_input_coverage_reviewed_exclusions,
     us_release_reform_coverage_probes,
 )
+from populace.build.us_runtime.release_target_parity import (
+    SSI_RECIPIENT_RED_LINE_FAMILIES,
+    US_TARGET_PARITY_FEED_FAMILIES_RESOURCE,
+    US_TARGET_PARITY_MANIFEST_RESOURCE,
+    TargetFamily,
+    TargetParityManifest,
+    assert_target_parity_manifest_current,
+    load_target_parity_feed_families,
+    load_target_parity_manifest,
+    registry_target_family_ids,
+    us_release_target_parity_compiled_families,
+    us_release_target_parity_gate,
+    us_release_target_parity_reviewed_exclusions,
+    us_target_family_id,
+)
 from populace.build.us_runtime.retirement_contributions import (
     US_RETIREMENT_CONTRIBUTION_NONCONSTANT_PERSON_COLUMNS,
     US_RETIREMENT_CONTRIBUTION_OUTPUT_COLUMNS,
@@ -1602,6 +1617,19 @@
     "us_release_input_coverage_required_columns",
     "us_release_input_coverage_reviewed_exclusions",
     "us_release_reform_coverage_probes",
+    "SSI_RECIPIENT_RED_LINE_FAMILIES",
+    "US_TARGET_PARITY_FEED_FAMILIES_RESOURCE",
+    "US_TARGET_PARITY_MANIFEST_RESOURCE",
+    "TargetFamily",
+    "TargetParityManifest",
+    "assert_target_parity_manifest_current",
+    "load_target_parity_feed_families",
+    "load_target_parity_manifest",
+    "registry_target_family_ids",
+    "us_release_target_parity_compiled_families",
+    "us_release_target_parity_gate",
+    "us_release_target_parity_reviewed_exclusions",
+    "us_target_family_id",
     "us_reform_coverage_smoke_gate",
     "us_register_consistency_gate",
     "us_register_contradictions",

packages/populace-build/src/populace/build/us_runtime/fiscal_targets.py

@@ -2043,6 +2043,8 @@ def _reference_from_ledger_fact(
                 include_congressional_district_targets
             ),
         )
+    if source_name == "ssa":
+        return _ssa_ssi_reference_from_fact(fact, target_period=target_period)
     if source_name == "jct":
         return None
     return _direct_reference_from_fact(fact, target_period=target_period)
@@ -2330,6 +2332,120 @@ def _population_age_reference_from_fact(
     )
 
 
+# SSA by-area record sets carry an eligibility category (total/aged/blind/
+# disabled) fused into ``layout.groupby_value_id`` (``all_areas_total``,
+# ``alabama_aged`` …). Only the all-category ``total`` has a PolicyEngine-US
+# counterpart: the model computes SSI receipt and amount but not the SSI
+# eligibility-category split, so aged/blind/disabled sub-rows are reviewed
+# exclusions in the target-parity manifest rather than silent drops.
+_SSA_OASDI_SSI_PAYMENTS_RECORD_SET_TOKEN = "oasdi_ssi_payments"
+_SSA_SSI_CALIBRATABLE_AREA_CATEGORY = "total"
+#: Engine-computed SSI counterpart both by-area families bind through. Receipt
+#: is an indicator sum of person-level ``ssi`` (recipients); federal payments
+#: are its dollar sum — the same variable the national ``ssi_total`` payment
+#: target already materializes.
+_SSA_SSI_BASE_VARIABLE = "ssi"
+SSA_SSI_RECIPIENTS_TARGET_ROLE = "ssi_recipients"
+SSA_SSI_STATE_PAYMENTS_TARGET_ROLE = "ssi_state_payments"
+
+
+def _ssa_area_category(fact: object) -> str:
+    """The SSA by-area eligibility category (``total``/``aged``/``blind``/...).
+
+    Encoded as the suffix of ``layout.groupby_value_id``; empty when the fact is
+    not an area-category row (e.g. the national OASDI payment aggregates).
+    """
+    groupby_value_id = _str_at(fact, "layout", "groupby_value_id")
+    if not groupby_value_id:
+        return ""
+    return groupby_value_id.rsplit("_", 1)[-1]
+
+
+def _ssa_ssi_reference_from_fact(
+    fact: object,
+    *,
+    target_period: int | str,
+) -> LedgerTargetReference | None:
+    """Compile an SSA (``source_name == "ssa"``) fact into a US target.
+
+    Three SSA record sets reach here:
+
+    - ``oasdi_ssi_payments`` — the six national OASDI benefit and SSI payment
+      aggregates. Delegated unchanged to :func:`_direct_reference_from_fact` so
+      the standing ``DIRECT_LEDGER_TARGETS`` ``ssa`` mappings (family ``ssa``:
+      ``social_security_total`` … ``ssi_total``) never regress.
+    - ``ssi_recipients.by_area_category`` — SSI recipients (a count). The
+      all-category ``total`` maps to an indicator sum of engine ``ssi`` receipt
+      at national and state grain (role ``ssi_recipients``). This is the
+      ``nation/ssa/ssi_recipients`` administrative family the retired
+      us-data/eCPS pipeline calibrated to that the populace registry dropped.
+    - ``ssi_payments.by_area_category`` — SSI federal payments (a dollar sum).
+      The national ``all_areas_total`` equals the ``oasdi_ssi_payments``
+      ``ssi_payments`` figure already compiled as ``ssi_total``, so only the
+      state ``total`` rows the national OASDI table does not carry are compiled
+      here (role ``ssi_state_payments``).
+
+    Non-``total`` eligibility categories (aged/blind/disabled) return ``None``;
+    PolicyEngine-US does not model the SSI eligibility-category split, so those
+    sub-rows are reviewed exclusions in the target-parity manifest.
+    """
+    record_set_id = _normalized_record_set_id(_str_at(fact, "layout", "record_set_id"))
+    if _SSA_OASDI_SSI_PAYMENTS_RECORD_SET_TOKEN in record_set_id:
+        return _direct_reference_from_fact(fact, target_period=target_period)
+
+    measure_id = _measure_id(fact)
+    if measure_id == "recipient_count":
+        target_role = SSA_SSI_RECIPIENTS_TARGET_ROLE
+        measure_mode = "indicator_sum"
+    elif measure_id == "payment_amount":
+        target_role = SSA_SSI_STATE_PAYMENTS_TARGET_ROLE
+        measure_mode = "sum"
+    else:
+        return None
+
+    if _ssa_area_category(fact) != _SSA_SSI_CALIBRATABLE_AREA_CATEGORY:
+        return None
+
+    geography_level = _geography_level(fact)
+    if geography_level == "state":
+        state_fips = _state_fips(fact)
+        if state_fips is None:
+            return None
+    elif geography_level == "country":
+        # The national by-area SSI payment duplicates the OASDI-table ssi_total
+        # already compiled from oasdi_ssi_payments; keep only the state rows.
+        if measure_id == "payment_amount":
+            return None
+        state_fips = None
+    else:
+        return None
+
+    source_record_id = _source_record_id(fact)
+    if not source_record_id:
+        return None
+
+    metadata = {
+        "materializer": "policyengine_variable",
+        "measure_mode": measure_mode,
+        "base_variable": _SSA_SSI_BASE_VARIABLE,
+        "target_role": target_role,
+        "source_measure_id": measure_id,
+        "source_period": str(_period_value(fact)),
+        "target_period": str(target_period),
+    }
+    if state_fips:
+        metadata["state_fips"] = state_fips
+    return LedgerTargetReference(
+        name=source_record_id,
+        ledger_source_record_id=source_record_id,
+        entity="household",
+        measure=source_record_id,
+        period=target_period,
+        family="ssa",
+        metadata=metadata,
+    )
+
+
 def _direct_reference_from_fact(
     fact: object,
     *,