Blocking Table 1.4 dollar-row fit + QRF tail-concentration gates; export-guard both CGD route legs (#462)

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

@@ -64,6 +64,7 @@ def _assert_frame_compatible(version: str, required: tuple[int, int]) -> None:
     GateReport,
     GateResult,
     TargetCoverageRequirement,
+    TargetFitRequirement,
     aggregate_admin_gate,
     default_valued_columns_gate,
     enum_domain_gate,
@@ -81,6 +82,8 @@ def _assert_frame_compatible(version: str, required: tuple[int, int]) -> None:
     source_coverage_gate,
     source_stage_input_coverage_gate,
     support_gate,
+    tail_concentration_gate,
+    target_fit_gate,
     target_profile_coverage_gate,
     target_surface_gate,
     weights_audit_gate,
@@ -146,6 +149,7 @@ def _assert_frame_compatible(version: str, required: tuple[int, int]) -> None:
     "STAGING_SCHEMA_VERSION",
     "StagingTelemetry",
     "TargetCoverageRequirement",
+    "TargetFitRequirement",
     "LedgerConsumerArtifact",
     "LedgerTargetMapping",
     "LedgerTargetSelection",
@@ -172,6 +176,8 @@ def _assert_frame_compatible(version: str, required: tuple[int, int]) -> None:
     "select_ledger_targets_from_jsonl",
     "summarize_rotations",
     "support_gate",
+    "tail_concentration_gate",
+    "target_fit_gate",
     "target_profile_coverage_gate",
     "target_spec_from_ledger_fact",
     "target_surface_gate",

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

@@ -333,6 +333,10 @@
   "salt_refund_income": {
    "status": "required"
   },
+  "schedule_d_capital_gain_distributions": {
+   "note": "Schedule D line 13 route leg of the #282 capital-gain-distributions split (memo component of long_term_capital_gains, written by the capital_gain_distributions source stage); required with NO reviewed exclusion per PolicyEngine/populace#462 so a release whose export drops the route (the Build M live default shipped it at $0 while non_sch_d_capital_gains carried 7.3x its SOI target) fails the coverage gate. Currently absent — this is the intended red gate until the Build N rebuild carries the split through.",
+   "status": "required"
+  },
   "selected_marketplace_plan_benchmark_ratio": {
    "status": "required"
   },
@@ -519,11 +523,11 @@
   }
  },
  "counts": {
-  "required": 158,
+  "required": 159,
   "reviewed_exclusion": 8,
-  "total": 166
+  "total": 167
  },
- "derivation": "Required surface = input columns in the pinned, sha-verified ecps_parity_reference.json populated layers, plus the documented post-reference fsla_overtime_premium, qualified_passenger_vehicle_loan_interest, five desired retirement-contribution inputs, and meets_ssi_disability_criteria required by shipped validation probes. status='reviewed_exclusion' for ecps_parity_known_gaps.json entries (reason+issue from that register); EXCEPT every primary-source restoration pinned by RESTORED_REFERENCE_ECPS_REQUIRED_INPUTS (including the Section 199A QBI family), and the SSI countable-resource asset inputs (bank_account_assets, stock_assets, bond_assets), which are status='required' with NO exclusion per PolicyEngine/populace#368 so the gate fails on today's artifacts and asset restoration (Deliverable 2) turns it green. All other populated layers are 'required'. Regenerate with tools/build_us_release_input_coverage_manifest.py.",
+ "derivation": "Required surface = input columns in the pinned, sha-verified ecps_parity_reference.json populated layers, plus the documented post-reference fsla_overtime_premium, qualified_passenger_vehicle_loan_interest, five desired retirement-contribution inputs, meets_ssi_disability_criteria required by shipped validation probes, and the #282 Schedule-D capital-gain-distributions route leg schedule_d_capital_gain_distributions (PolicyEngine/populace#462). status='reviewed_exclusion' for ecps_parity_known_gaps.json entries (reason+issue from that register); EXCEPT every primary-source restoration pinned by RESTORED_REFERENCE_ECPS_REQUIRED_INPUTS (including the Section 199A QBI family), and the SSI countable-resource asset inputs (bank_account_assets, stock_assets, bond_assets), which are status='required' with NO exclusion per PolicyEngine/populace#368 so the gate fails on today's artifacts and asset restoration (Deliverable 2) turns it green. All other populated layers are 'required'. Regenerate with tools/build_us_release_input_coverage_manifest.py.",
  "description": "Declared full-coverage contract for a US release: every input column the reference eCPS exports must be persisted as a key with non-default signal, or carry a reviewed exclusion. Enforced as a hard release gate (populace.build.us_runtime.release_input_coverage) that generalizes assert_required_us_release_source_columns from 5 columns to the full eCPS input surface.",
  "issue": "PolicyEngine/populace#368",
  "reference": {

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

@@ -561,6 +561,7 @@
 from populace.build.us_runtime.release_input_coverage import (
     POST_REFERENCE_ECPS_REQUIRED_INPUTS,
     SSI_COUNTABLE_RESOURCE_ASSETS,
+    US_CGD_ROUTE_REQUIRED_INPUTS,
     US_RELEASE_INPUT_COVERAGE_RESOURCE,
     ReformCoverageProbe,
     ReleaseInputColumn,
@@ -1644,6 +1645,7 @@
     "assert_validation_leaf_registry_current",
     "SSI_COUNTABLE_RESOURCE_ASSETS",
     "POST_REFERENCE_ECPS_REQUIRED_INPUTS",
+    "US_CGD_ROUTE_REQUIRED_INPUTS",
     "US_RELEASE_INPUT_COVERAGE_RESOURCE",
     "ReformCoverageProbe",
     "ReleaseInputColumn",

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

@@ -106,6 +106,7 @@
 )
 
 __all__ = [
+    "US_CGD_ROUTE_REQUIRED_INPUTS",
     "US_RELEASE_INPUT_COVERAGE_RESOURCE",
     "POST_REFERENCE_ECPS_REQUIRED_INPUTS",
     "RESTORED_REFERENCE_ECPS_REQUIRED_INPUTS",
@@ -124,8 +125,9 @@
 
 # The frozen reference artifact predates the retired pipeline's export of the
 # pure FLSA overtime-premium input, OBBBA's distinct qualifying passenger-
-# vehicle interest leaf, and the final pipeline's five desired retirement-
-# contribution inputs, and its final SIPP-imputed SSI disability criterion.
+# vehicle interest leaf, the final pipeline's five desired retirement-
+# contribution inputs, its final SIPP-imputed SSI disability criterion, and
+# the #282 capital-gain-distributions route split's Schedule-D leg.
 # These are hard requirements because their shipped validation rows otherwise
 # become structural zeroes.
 POST_REFERENCE_ECPS_REQUIRED_INPUTS = frozenset(
@@ -137,6 +139,7 @@
         "traditional_ira_contributions_desired",
         "roth_ira_contributions_desired",
         "self_employed_pension_contributions_desired",
+        "schedule_d_capital_gain_distributions",
         *US_SSI_DISABILITY_CRITERIA_OUTPUT_COLUMNS,
     }
 )
@@ -197,6 +200,23 @@
     "bond_assets",
 )
 
+#: The two legs of the #282 capital-gain-distributions route split
+#: (populace#462 / #361 remedy): the direct route reported on Form 1040 line 7
+#: without Schedule D (``non_sch_d_capital_gains``, PUF E01100, the SOI Pub
+#: 1304 Table 1.4 "capital gain distributions" concept) and the Schedule D
+#: line 13 route (``schedule_d_capital_gain_distributions``, a memo component
+#: of ``long_term_capital_gains`` written by the ``capital_gain_distributions``
+#: source stage). The Build M live default shipped the direct leg 7.3x over
+#: its SOI dollar target while the Schedule-D leg was absent from the export
+#: entirely. Both ship as hard requirements with NO reviewed exclusion, so a
+#: release whose export drops either route leg fails the coverage gate — red
+#: on today's artifacts by design until the Build N rebuild carries the split
+#: through.
+US_CGD_ROUTE_REQUIRED_INPUTS = (
+    "non_sch_d_capital_gains",
+    "schedule_d_capital_gain_distributions",
+)
+
 
 @dataclass(frozen=True)
 class ReleaseInputColumn:
@@ -656,6 +676,20 @@ def assert_release_input_coverage_manifest_current(
                 "required manifest column (#368)."
             )
 
+    for route_leg in US_CGD_ROUTE_REQUIRED_INPUTS:
+        if route_leg in reviewed:
+            failures.append(
+                f"{route_leg}: capital-gain-distributions route leg is a "
+                "reviewed exclusion, but #462 requires both #282 route legs "
+                "be hard requirements with no exclusion so a release that "
+                "drops either route from the export fails the coverage gate."
+            )
+        elif route_leg not in required:
+            failures.append(
+                f"{route_leg}: capital-gain-distributions route leg must be a "
+                "required manifest column (#462)."
+            )
+
     for column in RESTORED_REFERENCE_ECPS_REQUIRED_INPUTS:
         if column in reviewed:
             failures.append(