Document the work-program participation inputs as unsourced assumptions

packages/populace-build/tests/test_us_documented_absent_inputs.py

@@ -0,0 +1,67 @@
+"""Contract tests for the documented-absent-inputs register (populace #351/#249)."""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+from pathlib import Path
+
+
+def _load_builder_module():
+    root = Path(__file__).resolve().parents[3]
+    tools_path = str(root / "tools")
+    if tools_path not in sys.path:
+        sys.path.insert(0, tools_path)
+    path = root / "tools" / "build_us_fiscal_refresh_release.py"
+    spec = importlib.util.spec_from_file_location(
+        "build_us_fiscal_refresh_release", path
+    )
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+#: The unsourced SNAP work-requirement input families: exemption inputs
+#: with no survey source (#351) and the work-program participation
+#: family (#249).
+_EXPECTED = {
+    "is_homeless",
+    "was_in_foster_care",
+    "is_incapable_of_self_care",
+    "is_snap_work_program_participant",
+    "weekly_snap_work_program_hours",
+    "is_snap_workfare_participant",
+}
+
+
+def test_register_covers_exactly_the_known_unsourced_inputs() -> None:
+    builder = _load_builder_module()
+    assert set(builder.US_DOCUMENTED_ABSENT_INPUTS) == _EXPECTED
+
+
+def test_every_entry_names_a_tracking_issue() -> None:
+    builder = _load_builder_module()
+    for column, reason in builder.US_DOCUMENTED_ABSENT_INPUTS.items():
+        assert re.search(r"PolicyEngine/populace#\d+", reason), (
+            f"{column}: reason must cite a tracking issue"
+        )
+
+
+def test_seeded_inputs_are_not_documented_as_absent() -> None:
+    # These are produced by stages; listing them here would contradict
+    # the build.
+    builder = _load_builder_module()
+    for column in ("is_pregnant", "is_disabled", "is_snap_abawd_discretionary_exempt"):
+        assert column not in builder.US_DOCUMENTED_ABSENT_INPUTS
+
+
+def test_register_is_disjoint_from_the_degenerate_exclusions() -> None:
+    # The reviewed-exclusions register covers PERSISTED columns stuck at
+    # defaults; this register covers columns that are not persisted at
+    # all. An input in both would be contradictory.
+    builder = _load_builder_module()
+    assert not set(builder.US_DOCUMENTED_ABSENT_INPUTS) & set(
+        builder.US_DEGENERATE_INPUT_REVIEWED_EXCLUSIONS
+    )

tools/build_us_fiscal_refresh_release.py

@@ -468,7 +468,8 @@ def _automatic_gc_suspended():
 
 #: Person inputs SNAP work-requirement rules read that have NO CPS ASEC
 #: source and are not seeded: they default to False in the engine, so the
-#: exemption channels they drive never fire (populace #351). They are not
+#: compliance/exemption channels they drive never fire (populace #351,
+#: #249 for the work-program family). They are not
 #: persisted columns, so the degenerate-input gate cannot see them; this
 #: register makes the assumption visible in every release manifest instead.
 #: is_pregnant is NOT here: the pregnancy stage seeds it.
@@ -494,6 +495,23 @@ def _automatic_gc_suspended():
         "exemptions rely on the disability battery only "
         "(PolicyEngine/populace#351)."
     ),
+    "is_snap_work_program_participant": (
+        "No ASEC item measures SNAP E&T or qualifying work-program "
+        "participation, so compliance via program participation never "
+        "fires; USDA reports E&T reaches a small minority of "
+        "participants, so the always-False default understates "
+        "compliance only modestly (PolicyEngine/populace#249)."
+    ),
+    "weekly_snap_work_program_hours": (
+        "No ASEC item measures qualifying work-program hours, so combined "
+        "work-plus-program hours toward the 20-hour ABAWD test omit "
+        "program hours (PolicyEngine/populace#249)."
+    ),
+    "is_snap_workfare_participant": (
+        "No ASEC item measures workfare participation under 7 CFR "
+        "273.7(m), which satisfies the ABAWD requirement regardless of "
+        "hours; defaults False (PolicyEngine/populace#249)."
+    ),
 }
 US_ACA_MARKETPLACE_STAGE = "aca_marketplace_inputs"
 US_ACA_SOURCE_OUTPUT_COLUMNS = US_HEALTH_INPUT_NONCONSTANT_COLUMNS