Derive hours-worked inputs from ASEC reported hours

packages/populace-build/src/populace/build/source_manifest.py

@@ -50,6 +50,7 @@
         "compute_ratio",
         "declare_income_reference_offset",
         "derive",
+        "derive_hours_worked",
         "derive_immigration_status",
         "derive_puf_policyengine_variables",
         "derive_mortgage_balance_hints",

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

@@ -346,14 +346,13 @@
         "hourly_wage",
         "is_paid_hourly",
         "is_union_member_or_covered",
-        "weekly_hours_worked_before_lsr",
         "fsla_overtime_premium"
       ],
       "nonnegative_outputs": [
         "hourly_wage",
-        "weekly_hours_worked_before_lsr",
         "fsla_overtime_premium"
-      ]
+      ],
+      "notes": "Usual weekly hours are owned by the hours_worked stage (ASEC HRSWK), matching the retired enhanced-CPS pipeline mapping; this stage consumes them as predictors."
     },
     {
       "stage": "meps_esi_premiums",
@@ -486,6 +485,40 @@
       ],
       "notes": "Citizenship is measured (PRCITSHP), not imputed. Non-citizens with any ASEC-UA legal-status indicator (Van Hook et al., SSRN 4662801) become OTHER_NON_CITIZEN. The CPS carries no work-authorization variable, so among residual non-citizens, workers and students spill to NON_CITIZEN_VALID_EAD in deterministic seeded order until the remaining undocumented worker count matches Pew's 8.3M and the undocumented student count matches the Higher Ed Immigration Portal's ~408k \u2014 the only forced margins. The total undocumented population is emergent (\u224813M on the 2024 ASEC, within the range of published 2023-24 estimates) and is gated against Pew's 11.0M 2022 anchor with a coarse plausibility band rather than forced; reconciling the level is the calibration lane's job. Immigration-status tags carry only statutory tests the data supports: DACA (arrival cohort among EAD holders) and CUBAN_HAITIAN_ENTRANT (nativity plus post-1980 arrival); other documented non-citizens stay LEGAL_PERMANENT_RESIDENT, the modal true status \u2014 blanket REFUGEE/TPS labels are deliberately not fabricated because they would mislabel millions and over-grant refugee-class benefit exemptions."
     },
+    {
+      "stage": "hours_worked",
+      "survey": "Census CPS ASEC",
+      "source": "https://www.census.gov/programs-surveys/cps.html",
+      "grain": "person",
+      "artifacts": [
+        {
+          "kind": "public_microdata",
+          "format": "census_asec",
+          "vintage": "build_year",
+          "locator": "Census CPS ASEC person file usual weekly hours (HRSWK), reference-week hours (A_HRS1), and weeks worked (WKSWORK)"
+        }
+      ],
+      "operations": [
+        {
+          "kind": "read_table",
+          "table": "person"
+        },
+        {
+          "kind": "derive_hours_worked"
+        }
+      ],
+      "outputs": [
+        "weekly_hours_worked_before_lsr",
+        "hours_worked_last_week",
+        "weeks_worked"
+      ],
+      "nonnegative_outputs": [
+        "weekly_hours_worked_before_lsr",
+        "hours_worked_last_week",
+        "weeks_worked"
+      ],
+      "notes": "Direct mappings of measured ASEC hours variables, identical to the retired enhanced-CPS pipeline: weekly_hours_worked_before_lsr <- HRSWK (usual hours per week last year, 0 for non-workers), hours_worked_last_week <- A_HRS1, weeks_worked <- WKSWORK clipped to [0, 52]. Nothing is imputed. Without this stage PolicyEngine-US defaults every person to 40 weekly hours, so the SNAP 30-hour general and 20-hour ABAWD work requirements pass universally (populace #242/#248). HRSWK is an annual usual-hours measure while the ABAWD standard is a monthly 80-hour test; week-by-week volatility is not observable in the CPS and is deliberately out of scope."
+    },
     {
       "stage": "mortgage_conversion",
       "survey": "IRS PUF 2015 (uprated) + Fed SCF 2022",

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

@@ -108,6 +108,17 @@
     us_geography_ladder_gate,
     with_household_us_geography_ladder,
 )
+from populace.build.us_runtime.hours_worked import (
+    US_HOURS_WORKED_NONCONSTANT_PERSON_COLUMNS,
+    US_HOURS_WORKED_OUTPUT_COLUMNS,
+    US_HOURS_WORKED_REQUIRED_SOURCE_COLUMNS,
+    US_HOURS_WORKED_STAGE_NAME,
+    derive_us_hours_worked_from_manifest,
+    us_hours_worked_signal_gate,
+    us_hours_worked_stage_spec,
+    us_hours_worked_summary,
+    with_us_hours_worked_inputs,
+)
 from populace.build.us_runtime.immigration import (
     IMMIGRATION_STATUS_VALUES,
     SSN_CARD_TYPE_VALUES,
@@ -259,6 +270,15 @@
     "US_IMMIGRATION_REQUIRED_SOURCE_COLUMNS",
     "US_IMMIGRATION_STAGE_NAME",
     "UndocumentedControls",
+    "US_HOURS_WORKED_NONCONSTANT_PERSON_COLUMNS",
+    "US_HOURS_WORKED_OUTPUT_COLUMNS",
+    "US_HOURS_WORKED_REQUIRED_SOURCE_COLUMNS",
+    "US_HOURS_WORKED_STAGE_NAME",
+    "derive_us_hours_worked_from_manifest",
+    "us_hours_worked_signal_gate",
+    "us_hours_worked_stage_spec",
+    "us_hours_worked_summary",
+    "with_us_hours_worked_inputs",
     "derive_us_immigration_status_from_manifest",
     "us_immigration_composition_gate",
     "us_immigration_composition_summary",
@@ -452,6 +472,16 @@ def to_manifest(self) -> dict[str, object]:
             "undocumented population/worker/student control totals."
         ),
     ),
+    US_HOURS_WORKED_STAGE_NAME: DonorSpec(
+        survey="Census CPS ASEC",
+        source="https://www.census.gov/programs-surveys/cps.html",
+        notes=(
+            "Hours-worked inputs mapped directly from measured ASEC person "
+            "variables (HRSWK, A_HRS1, WKSWORK) — nothing imputed. Without "
+            "them the engine defaults every person to 40 weekly hours and "
+            "hours-conditioned rules (SNAP work requirements) become no-ops."
+        ),
+    ),
     "puf_tax_detail": DonorSpec(
         survey="IRS PUF 2015 (uprated)",
         source="https://www.irs.gov/statistics/soi-tax-stats-individual-public-use-microdata-files",
@@ -498,6 +528,7 @@ def to_manifest(self) -> dict[str, object]:
     "unit_assignment",
     "derive_cps_carried",
     US_IMMIGRATION_STAGE_NAME,
+    US_HOURS_WORKED_STAGE_NAME,
     US_PUF_SUPPORT_STAGE_NAME,
     "puf_tax_detail",
     "capital_gain_distributions",