From 54509aa3119038a991fccf6b1fa1a247c9d8a934 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 13:21:37 -0400
Subject: [PATCH 1/7] chore: start populace #462 fix 3b progress log

---
 PROGRESS.md | 72 ++++++++++++++++-------------------------------------
 1 file changed, 21 insertions(+), 51 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index 9cda6b80..8b5db86e 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -2,60 +2,30 @@
 
 ## State
 
-Scope 3a is complete. The declared `capital_gain_distributions` executor now
-runs in both PUF support base paths after `qrf_finalization` and before
-`qbi_reconciliation`; focused end-to-end stage-record, semantic, rerun, and
-release-coverage tests are green. The branch is fully committed and remains
-unpushed.
+Populace #462 fix 3b is in progress on `qrf-tail-bound-462`, starting from the
+clean `origin/main` commit that includes #477, #478, #479, and #480. The settled
+design is a per-target weighted-donor-quantile clip at the PUF tax-detail
+finalizer seam; no manifest, `populace-fit`, or other pipeline stage changes are
+in scope.
 
 ## Done
 
-- Confirmed the worktree is on `cgd-split-462` and starts clean.
-- Read the complete stage declaration, share resource, executor, runtime, base
-  builders, outer-stage manifest recorder, and relevant tests.
-- Confirmed the declared 9.8526% parameter is a Schedule-D share of eligible
-  long-term gains, not a partition share for the existing CGD total.
-- Confirmed the executor adds only the Schedule-D output, leaves the direct
-  route untouched, and fails loudly when the output already exists.
-- Located the otherwise-correct builder insertion point after PUF QRF
-  finalization and before QBI reconciliation, and confirmed how an outer stage
-  would be recorded in `stage_run_context.json`.
-- Documented the blocking semantic, magnitude, conservation, and grain
-  conflicts in `CONTRACT_FINDINGS.md` without changing implementation or tests.
-- Recorded the user's adjudication: the conservation requirement is withdrawn,
-  the existing executor behavior is authoritative, and QRF machinery is out of
-  scope.
-- Retitled the resolved adjudication record from `BLOCKED.md` to
-  `CONTRACT_FINDINGS.md` while retaining its analysis.
-- Traced the existing entity-grain convention: use `Frame.place` to sum PUF
-  person inputs to tax units, then first-person carry the memo output because
-  PolicyEngine re-aggregates that person input to the filing unit.
-- Added `capital_gain_distributions` to the outer pipeline and monolithic base
-  path at the adjudicated insertion point, calling the unchanged manifest
-  executor through `run_source_stage`.
-- Preserved both original PUF inputs and surfaced any pre-existing output to
-  the executor so its existing overwrite refusal remains the rerun contract.
-- Extended the existing capital-gain fixture through the actual named outer
-  stage: tax-unit memo semantics, unchanged PUF inputs, first-person output
-  placement, automatic pipeline/completed/stage-record entries, and the
-  executor-owned rerun failure are pinned end to end.
-- Updated the locked pipeline/base-order tests; the focused builder and
-  executor suites pass (58 tests), and Ruff is clean for the touched files.
-- Confirmed the release input-coverage generator is already byte-identical:
-  both capital-gain route legs are required independently of builder stage
-  presence, and its focused six-test sync/route guarantee suite passes. No
-  generated manifest rewrite is needed.
-- Ran the full suite through 100%. It reported the two declared pre-existing
-  release-parity `TestRegeneration` failures and two unrelated UK reference
-  regeneration failures caused by licensed artifacts being present in the
-  user cache while this worktree's virtual environment lacks
-  `policyengine_uk`; no failure traces to the scope-3a changes.
-- Confirmed the third declared pre-existing failure, educator `FakeQRF`, is
-  skipped in this environment because the `policyengine_us` optional
-  dependency is absent. This branch still predates its main-branch fix, so the
-  skip does not imply that the known issue disappeared.
+- Confirmed the worktree is on `qrf-tail-bound-462`, clean, and exactly at
+  `origin/main` (`3b17aaf`).
+- Read the required GitNexus exploration and impact-analysis workflows.
+- Confirmed the GitNexus MCP index/tools are unavailable in this workspace;
+  repository-native symbol and call-site inspection will provide the fallback
+  impact analysis.
+- Preserved the prior fix-3a history in Git; this file now tracks the new fix-3b
+  work from its starting commit.
 
 ## Next
 
-- No scope-3a implementation work remains. Keep the committed branch unpushed
-  for review/integration.
+- Inspect `puf_support.py`, its finalizer telemetry pattern, all neighboring
+  snapping/pruning/calibration sets, and existing finalizer fixtures.
+- Add the weighted inverse-CDF helper, settled configuration, fail-loud entry
+  validation, tax-unit clipping, and per-target diagnostics.
+- Add the requested focused, regression, failure, and real-donor pin tests.
+- Run Ruff, focused tests, and the full `packages/populace-build/tests` suite;
+  commit every coherent step and keep the branch unpushed.
+- Write the completed verification report to the designated output file.

From f5bebb822dd534ada588fd9845e099639ad3518f Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 13:28:02 -0400
Subject: [PATCH 2/7] docs: record #462 fix 3b design verification

---
 PROGRESS.md | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index 8b5db86e..999e3019 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -18,11 +18,30 @@ in scope.
   impact analysis.
 - Preserved the prior fix-3a history in Git; this file now tracks the new fix-3b
   work from its starting commit.
+- Located the existing public inverse-CDF implementation,
+  `populace.frame.wquantile`, including its hand-computed uneven-weight tests at
+  and above an exact cumulative boundary; the finalizer will reuse it.
+- Mapped the finalizer ordering: raw tax-unit draws are normalized/snapped,
+  reconciled, placed on tax units or people, sparsified, then signed-mass
+  calibrated. The new bound belongs before this loop and is constrained to
+  passthrough outputs, so it cannot interact with those later transforms.
+- Mapped the publishable telemetry seam: optional finalizer diagnostics can be
+  carried through both the monolithic imputation helper and checkpointed QRF
+  finalization into the `qrf_finalization` stage metadata and final build
+  summary, alongside the existing weights-audit record.
+- Resolved targeted-test compatibility without weakening production drift
+  checks: configuration keys are validated against the canonical production
+  output universe, while a custom subset finalization applies only configured
+  keys present in that subset. Requiring every global key in each custom subset
+  would break the unchanged snapping, pruning, signed-calibration, educator,
+  and checkpoint-equivalence fixtures.
+- Verified the exact pinned local PUF exists at the requested path and SHA. Its
+  actual positive tax-unit donor support has weighted inverse-CDF p99.9
+  `211500.84797884867`, finite and positive and below the required `594483.0`
+  ceiling; the design-block condition is not triggered.
 
 ## Next
 
-- Inspect `puf_support.py`, its finalizer telemetry pattern, all neighboring
-  snapping/pruning/calibration sets, and existing finalizer fixtures.
 - Add the weighted inverse-CDF helper, settled configuration, fail-loud entry
   validation, tax-unit clipping, and per-target diagnostics.
 - Add the requested focused, regression, failure, and real-donor pin tests.

From d6e8fee19ce6b801abac6202798a1037172561a9 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 13:36:24 -0400
Subject: [PATCH 3/7] Implement #462 fix 3b tail bound; defer draws to #481 and
 support_clip to #482

---
 .../build/us_runtime/puf_qrf_chain.py         |   3 +
 .../populace/build/us_runtime/puf_support.py  | 131 +++++++++++++++++-
 tools/build_us_puf_support_base.py            |  17 ++-
 3 files changed, 148 insertions(+), 3 deletions(-)

diff --git a/packages/populace-build/src/populace/build/us_runtime/puf_qrf_chain.py b/packages/populace-build/src/populace/build/us_runtime/puf_qrf_chain.py
index 9aa96ee4..7cab534a 100644
--- a/packages/populace-build/src/populace/build/us_runtime/puf_qrf_chain.py
+++ b/packages/populace-build/src/populace/build/us_runtime/puf_qrf_chain.py
@@ -336,6 +336,8 @@ def load_primary_puf_qrf_predictions(
 def finalize_primary_puf_qrf_chain(
     frame: Frame,
     checkpoint_dir: str | Path,
+    *,
+    tail_bound_diagnostics: list[dict[str, object]] | None = None,
 ) -> tuple[Frame, str]:
     """Finalize all raw checkpoints onto ``frame`` and return fit weight kind."""
 
@@ -358,6 +360,7 @@ def finalize_primary_puf_qrf_chain(
         predictions,
         person_outputs=_manifest_strings(manifest, "person_outputs"),
         tax_unit_outputs=_manifest_strings(manifest, "tax_unit_outputs"),
+        tail_bound_diagnostics=tail_bound_diagnostics,
     )
     initial_state = manifest.get("initial_state")
     if not isinstance(initial_state, dict):
diff --git a/packages/populace-build/src/populace/build/us_runtime/puf_support.py b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
index 209ba353..b2a8bf4b 100644
--- a/packages/populace-build/src/populace/build/us_runtime/puf_support.py
+++ b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
@@ -22,7 +22,7 @@
     US_QBI_NONNEGATIVE_OUTPUT_COLUMNS,
     US_QBI_OUTPUT_COLUMNS,
 )
-from populace.frame import US_SCHEMA, Frame, WeightKind, Weights
+from populace.frame import US_SCHEMA, Frame, WeightKind, Weights, wquantile
 from populace.frame.schema import EntitySchema
 
 QRF: Any | None = None
@@ -185,6 +185,15 @@ def target_order(self) -> tuple[str, ...]:
     }
 )
 
+# Interim weight-reintroduction at the finalize seam: the root fix
+# (weight-aware leaf draws) is #481, and the dead manifest support_clip is
+# #482. Tail bounds are defined only for passthrough outputs, which removes all
+# snapping, sparse-pruning, and signed-calibration ordering interactions by
+# construction.
+_PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES: dict[str, float] = {
+    "non_sch_d_capital_gains": 0.999
+}
+
 # ASEC directly measures recipient alimony. The PUF QRF therefore sparsifies
 # only the cloned PUF half for this leaf; pruning the ASEC half would discard
 # reported source observations. Expense has no ASEC analogue, so its zero ASEC
@@ -557,6 +566,7 @@ def impute_us_puf_tax_detail_support(
     n_estimators: int = 100,
     fit_records: list[FitWeightRecord] | None = None,
     raw_predictions_callback: Callable[[pd.DataFrame], None] | None = None,
+    tail_bound_diagnostics: list[dict[str, object]] | None = None,
 ) -> Frame:
     """Impute PUF-observed inputs onto the PUF support channel.
 
@@ -582,6 +592,9 @@ def impute_us_puf_tax_detail_support(
         raw_predictions_callback: Test-only observer called synchronously with
             the complete raw chained draws before any clipping, snapping, or
             finalization. Production callers leave it unset.
+        tail_bound_diagnostics: Optional output sink for the per-target tail-bound
+            records produced during finalization. Build callers publish these
+            records with the QRF-finalization telemetry.
     """
 
     if frame.schema != US_SCHEMA:
@@ -652,6 +665,7 @@ def impute_us_puf_tax_detail_support(
         predictions,
         person_outputs=person_outputs,
         tax_unit_outputs=tax_unit_outputs,
+        tail_bound_diagnostics=tail_bound_diagnostics,
     )
 
 
@@ -726,6 +740,7 @@ def finalize_us_puf_tax_detail_predictions(
     *,
     person_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
     tax_unit_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
+    tail_bound_diagnostics: list[dict[str, object]] | None = None,
 ) -> Frame:
     """Finalize a complete raw PUF QRF chain onto its support channel.
 
@@ -738,6 +753,7 @@ def finalize_us_puf_tax_detail_predictions(
     person_outputs = tuple(person_outputs)
     tax_unit_outputs = tuple(tax_unit_outputs)
     outputs = (*person_outputs, *tax_unit_outputs)
+    active_tail_bounds = _validated_tail_bound_quantiles(outputs)
     if tuple(predictions.columns) != outputs:
         raise ValueError(
             "PUF raw prediction columns must match the exact target order: "
@@ -760,6 +776,37 @@ def finalize_us_puf_tax_detail_predictions(
             "finalization."
         )
 
+    for output, quantile in active_tail_bounds.items():
+        try:
+            bound = _weighted_positive_donor_quantile(
+                donor[output], donor["weight"], quantile
+            )
+        except ValueError as exc:
+            if "no positive donor support" not in str(exc):
+                raise
+            raise ValueError(
+                f"PUF tax-detail tail-bound output {output!r} has no positive "
+                "donor support."
+            ) from None
+        values = predictions[output].to_numpy(dtype=np.float64, copy=False)
+        clipped = values > bound
+        clipped_mass_before = float(values[clipped].sum())
+        predictions.loc[clipped, output] = bound
+        clipped_mass_after = float(
+            predictions.loc[clipped, output].to_numpy(dtype=np.float64).sum()
+        )
+        if tail_bound_diagnostics is not None:
+            tail_bound_diagnostics.append(
+                {
+                    "output": output,
+                    "quantile": quantile,
+                    "bound_value": bound,
+                    "clipped_row_count": int(clipped.sum()),
+                    "clipped_mass_before": clipped_mass_before,
+                    "clipped_mass_after": clipped_mass_after,
+                }
+            )
+
     for column in outputs:
         if column in _PUF_TAX_DETAIL_NONNEGATIVE_OUTPUTS:
             predictions[column] = predictions[column].clip(lower=0.0)
@@ -1074,6 +1121,88 @@ def _tax_unit_model_frame(donor: pd.DataFrame) -> Frame:
     )
 
 
+def _validated_tail_bound_quantiles(outputs: Sequence[str]) -> dict[str, float]:
+    """Validate production tail-bound configuration and select active outputs."""
+
+    production_outputs = {
+        *PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
+        *PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
+    }
+    transformed_outputs = (
+        _PUF_TAX_DETAIL_DISCRETE_TAX_UNIT_OUTPUTS
+        | _PUF_TAX_DETAIL_BOOLEAN_PERSON_OUTPUTS
+        | _PUF_TAX_DETAIL_SPARSE_TAX_UNIT_OUTPUTS
+        | _PUF_TAX_DETAIL_SPARSE_PERSON_OUTPUTS
+        | _PUF_TAX_DETAIL_SIGNED_MASS_CALIBRATED_PERSON_OUTPUTS
+    )
+    requested = set(outputs)
+    active: dict[str, float] = {}
+    for output, configured_quantile in _PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES.items():
+        if output not in production_outputs:
+            raise ValueError(
+                f"PUF tax-detail tail-bound configured output {output!r} is "
+                "missing from outputs."
+            )
+        try:
+            quantile = float(configured_quantile)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"PUF tax-detail tail-bound quantile for {output!r} must be in "
+                f"(0, 1), got {configured_quantile!r}."
+            ) from exc
+        if not np.isfinite(quantile) or not 0.0 < quantile < 1.0:
+            raise ValueError(
+                f"PUF tax-detail tail-bound quantile for {output!r} must be in "
+                f"(0, 1), got {configured_quantile!r}."
+            )
+        if output in transformed_outputs:
+            raise ValueError(
+                f"PUF tax-detail output {output!r}: tail bound is defined for "
+                "passthrough outputs only."
+            )
+        if output in requested:
+            active[output] = quantile
+    return active
+
+
+def _weighted_positive_donor_quantile(
+    values: Sequence[Any],
+    weights: Sequence[Any],
+    quantile: float,
+) -> float:
+    """Return an inverse-CDF quantile over positive, weighted donor support."""
+
+    numeric_values = pd.to_numeric(pd.Series(values), errors="coerce").to_numpy(
+        dtype=np.float64
+    )
+    numeric_weights = pd.to_numeric(pd.Series(weights), errors="coerce").to_numpy(
+        dtype=np.float64
+    )
+    if len(numeric_values) != len(numeric_weights):
+        raise ValueError(
+            "PUF tail-bound donor values and weights must align, got "
+            f"{len(numeric_values)} values and {len(numeric_weights)} weights."
+        )
+    positive = numeric_values > 0.0
+    if not (positive & (numeric_weights > 0.0)).any():
+        raise ValueError("PUF tail-bound donor has no positive donor support.")
+    positive_donor = pd.DataFrame(
+        {
+            "tail_bound_value": numeric_values[positive],
+            "weight": numeric_weights[positive],
+        }
+    )
+    positive_frame = _tax_unit_model_frame(positive_donor)
+    return float(
+        wquantile(
+            positive_frame,
+            "tail_bound_value",
+            quantile,
+            entity="tax_unit",
+        )
+    )
+
+
 def _formula_owned_engine() -> Any | None:
     """A PolicyEngine-US adapter for formula metadata, or ``None`` if absent.
 
diff --git a/tools/build_us_puf_support_base.py b/tools/build_us_puf_support_base.py
index 48bc8775..87ade5c4 100644
--- a/tools/build_us_puf_support_base.py
+++ b/tools/build_us_puf_support_base.py
@@ -991,12 +991,14 @@ def _run_all(
     arrays = _read_h5_arrays(args.puf_h5)
     donor = puf_tax_unit_donor_from_arrays(arrays)
     _observe_frame_boundary(boundary_observer, "clone_feature_extraction", expanded)
+    tail_bound_diagnostics: list[dict[str, object]] = []
     if boundary_observer is None:
         imputed, weights_audit = impute_and_audit_us_puf_support(
             expanded,
             donor,
             seed=args.seed,
             n_estimators=args.n_estimators,
+            tail_bound_diagnostics=tail_bound_diagnostics,
         )
     else:
         imputed, weights_audit = impute_and_audit_us_puf_support(
@@ -1007,6 +1009,7 @@ def _run_all(
             raw_predictions_callback=lambda predictions: (
                 boundary_observer.observe_primary_qrf(expanded, predictions)
             ),
+            tail_bound_diagnostics=tail_bound_diagnostics,
         )
     _observe_frame_boundary(boundary_observer, "qrf_finalization", imputed)
     imputed, _ = _capital_gain_distributions_stage(args, imputed)
@@ -1383,6 +1386,7 @@ def _run_all(
         "puf_donor_rows": int(len(donor)),
         "puf_donor_columns": sorted(donor.columns.tolist()),
         "weights_audit": weights_audit,
+        "puf_tax_detail_tail_bounds": tail_bound_diagnostics,
         "qbi_inputs_signal": {
             "passed": qbi_inputs_gate.passed,
             "failures": list(qbi_inputs_gate.failures),
@@ -1859,8 +1863,11 @@ def _qrf_finalization_stage(
     args: argparse.Namespace,
     expanded: Frame,
 ) -> tuple[Frame, dict[str, object]]:
+    tail_bound_diagnostics: list[dict[str, object]] = []
     imputed, weight_kind = finalize_primary_puf_qrf_chain(
-        expanded, args.checkpoint_dir / "primary_qrf"
+        expanded,
+        args.checkpoint_dir / "primary_qrf",
+        tail_bound_diagnostics=tail_bound_diagnostics,
     )
     report = weights_audit_gate([FitWeightRecord(US_PUF_SUPPORT_FIT_NAME, weight_kind)])
     if not report.passed:
@@ -1870,7 +1877,8 @@ def _qrf_finalization_stage(
             "passed": report.passed,
             "failures": list(report.failures),
             "details": dict(report.details),
-        }
+        },
+        "puf_tax_detail_tail_bounds": tail_bound_diagnostics,
     }
 
 
@@ -2368,6 +2376,7 @@ def _export_staged_result(
         "puf_donor_rows": clone["puf_donor_rows"],
         "puf_donor_columns": clone["puf_donor_columns"],
         "weights_audit": qrf["weights_audit"],
+        "puf_tax_detail_tail_bounds": qrf["puf_tax_detail_tail_bounds"],
         **{name: signals[name] for name in required_signals},
         "congressional_district_assignment": stage_metadata[
             "congressional_district_assignment"
@@ -2409,6 +2418,7 @@ def impute_and_audit_us_puf_support(
     person_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
     tax_unit_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
     raw_predictions_callback: Callable[[pd.DataFrame], None] | None = None,
+    tail_bound_diagnostics: list[dict[str, object]] | None = None,
 ) -> tuple[Frame, dict]:
     """Impute the PUF support channel and audit the fit's resolved weight kind.
 
@@ -2437,6 +2447,8 @@ def impute_and_audit_us_puf_support(
             unchanged.
         raw_predictions_callback: Optional test-only observer for complete raw
             chained draws before finalization.
+        tail_bound_diagnostics: Optional output sink for publishable per-target
+            tail-bound finalization records.
 
     Returns:
         ``(imputed_frame, weights_audit)`` where ``weights_audit`` is the gate's
@@ -2459,6 +2471,7 @@ def impute_and_audit_us_puf_support(
         n_estimators=n_estimators,
         fit_records=fit_records,
         raw_predictions_callback=raw_predictions_callback,
+        tail_bound_diagnostics=tail_bound_diagnostics,
     )
     report = weights_audit_gate(fit_records)
     if not report.passed:

From 0de6d38aa699299f49df8e323e755383f365b3e5 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 13:47:46 -0400
Subject: [PATCH 4/7] Harden and test #462 fix 3b tail bound; retain #481/#482
 follow-ups

---
 PROGRESS.md                                   |  35 +-
 .../populace/build/us_runtime/puf_support.py  |  93 +++--
 .../tests/test_us_puf_support_base_builder.py |  35 ++
 .../tests/test_us_puf_tail_bound.py           | 335 ++++++++++++++++++
 4 files changed, 452 insertions(+), 46 deletions(-)
 create mode 100644 packages/populace-build/tests/test_us_puf_tail_bound.py

diff --git a/PROGRESS.md b/PROGRESS.md
index 999e3019..ba245553 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -6,7 +6,8 @@ Populace #462 fix 3b is in progress on `qrf-tail-bound-462`, starting from the
 clean `origin/main` commit that includes #477, #478, #479, and #480. The settled
 design is a per-target weighted-donor-quantile clip at the PUF tax-detail
 finalizer seam; no manifest, `populace-fit`, or other pipeline stage changes are
-in scope.
+in scope. The mechanism and focused tests are implemented; full-suite
+verification remains.
 
 ## Done
 
@@ -29,22 +30,32 @@ in scope.
   carried through both the monolithic imputation helper and checkpointed QRF
   finalization into the `qrf_finalization` stage metadata and final build
   summary, alongside the existing weights-audit record.
-- Resolved targeted-test compatibility without weakening production drift
-  checks: configuration keys are validated against the canonical production
-  output universe, while a custom subset finalization applies only configured
-  keys present in that subset. Requiring every global key in each custom subset
-  would break the unchanged snapping, pruning, signed-calibration, educator,
-  and checkpoint-equivalence fixtures.
+- Resolved targeted-test compatibility without weakening fail-loud validation:
+  the canonical production chain always activates the module configuration;
+  deliberately reduced/custom chains remain isolated unless they explicitly
+  supply a tail-bound mapping, which is then validated against their actual
+  output surface. This preserves the unchanged snapping, pruning,
+  signed-calibration, educator, and checkpoint-equivalence fixtures.
 - Verified the exact pinned local PUF exists at the requested path and SHA. Its
   actual positive tax-unit donor support has weighted inverse-CDF p99.9
   `211500.84797884867`, finite and positive and below the required `594483.0`
   ceiling; the design-block condition is not triggered.
+- Added the `non_sch_d_capital_gains` p99.9 configuration, positive-support
+  weighted-donor quantile wrapper, atomic entry validation, strict upper clip
+  before person allocation, and JSON-native per-target diagnostics.
+- Required an active bound to have a diagnostics sink, then carried those
+  records through both monolithic and checkpointed finalization into
+  `qrf_finalization` metadata and the final build summary; caps cannot be
+  silent.
+- Added focused tests for inverse-CDF boundaries, exact clipping/count/bit
+  behavior, unaffected outputs, every fail-loud case, atomic validation,
+  telemetry serialization, and the real donor pin.
+- Ran Ruff on all touched implementation/test files. The new tail-bound file,
+  unchanged PUF-support behavior file, QRF checkpoint-chain file, and base
+  builder telemetry file are green.
 
 ## Next
 
-- Add the weighted inverse-CDF helper, settled configuration, fail-loud entry
-  validation, tax-unit clipping, and per-target diagnostics.
-- Add the requested focused, regression, failure, and real-donor pin tests.
-- Run Ruff, focused tests, and the full `packages/populace-build/tests` suite;
-  commit every coherent step and keep the branch unpushed.
+- Run the full `packages/populace-build/tests` suite and perform the final
+  diff/impact review; keep the branch unpushed.
 - Write the completed verification report to the designated output file.
diff --git a/packages/populace-build/src/populace/build/us_runtime/puf_support.py b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
index b2a8bf4b..22f8a06e 100644
--- a/packages/populace-build/src/populace/build/us_runtime/puf_support.py
+++ b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
@@ -741,6 +741,7 @@ def finalize_us_puf_tax_detail_predictions(
     person_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
     tax_unit_outputs: Sequence[str] = PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
     tail_bound_diagnostics: list[dict[str, object]] | None = None,
+    tail_bound_quantiles: Mapping[str, float] | None = None,
 ) -> Frame:
     """Finalize a complete raw PUF QRF chain onto its support channel.
 
@@ -748,12 +749,30 @@ def finalize_us_puf_tax_detail_predictions(
     retain the recipient tax-unit index.  Clipping, snapping, reconciliation,
     placement, and sparsification happen only here, after every target has
     drawn; later targets therefore always condition on raw predecessor draws.
+
+    The canonical production chain uses the module tail-bound configuration.
+    Reduced/custom target chains opt in by passing ``tail_bound_quantiles`` so
+    their deliberately partial output surfaces remain isolated. Diagnostics
+    report unweighted sums of the affected raw tax-unit draws before and after
+    clipping; build callers must provide the sink and publish every active cap.
     """
 
     person_outputs = tuple(person_outputs)
     tax_unit_outputs = tuple(tax_unit_outputs)
     outputs = (*person_outputs, *tax_unit_outputs)
-    active_tail_bounds = _validated_tail_bound_quantiles(outputs)
+    production_chain = (
+        person_outputs == PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS
+        and tax_unit_outputs == PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS
+    )
+    configured_tail_bounds = (
+        _PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES
+        if tail_bound_quantiles is None and production_chain
+        else (tail_bound_quantiles or {})
+    )
+    active_tail_bounds = _validated_tail_bound_quantiles(
+        outputs,
+        configured_tail_bounds,
+    )
     if tuple(predictions.columns) != outputs:
         raise ValueError(
             "PUF raw prediction columns must match the exact target order: "
@@ -763,6 +782,26 @@ def finalize_us_puf_tax_detail_predictions(
     if missing_donor:
         raise ValueError(f"PUF finalization donor missing column(s): {missing_donor}.")
 
+    resolved_tail_bounds: dict[str, tuple[float, float]] = {}
+    for output, quantile in active_tail_bounds.items():
+        try:
+            bound = _weighted_positive_donor_quantile(
+                donor[output], donor["weight"], quantile
+            )
+        except ValueError as exc:
+            if "no positive donor support" not in str(exc):
+                raise
+            raise ValueError(
+                f"PUF tax-detail tail-bound output {output!r} has no positive "
+                "donor support."
+            ) from None
+        resolved_tail_bounds[output] = (quantile, bound)
+    if resolved_tail_bounds and tail_bound_diagnostics is None:
+        raise ValueError(
+            "PUF tax-detail tail-bound finalization requires a diagnostics sink; "
+            "tail bounds must not be silent."
+        )
+
     tax_unit_channel = support_channel_column("tax_unit")
     person_channel = support_channel_column("person")
     puf_mask = (
@@ -776,18 +815,7 @@ def finalize_us_puf_tax_detail_predictions(
             "finalization."
         )
 
-    for output, quantile in active_tail_bounds.items():
-        try:
-            bound = _weighted_positive_donor_quantile(
-                donor[output], donor["weight"], quantile
-            )
-        except ValueError as exc:
-            if "no positive donor support" not in str(exc):
-                raise
-            raise ValueError(
-                f"PUF tax-detail tail-bound output {output!r} has no positive "
-                "donor support."
-            ) from None
+    for output, (quantile, bound) in resolved_tail_bounds.items():
         values = predictions[output].to_numpy(dtype=np.float64, copy=False)
         clipped = values > bound
         clipped_mass_before = float(values[clipped].sum())
@@ -795,17 +823,16 @@ def finalize_us_puf_tax_detail_predictions(
         clipped_mass_after = float(
             predictions.loc[clipped, output].to_numpy(dtype=np.float64).sum()
         )
-        if tail_bound_diagnostics is not None:
-            tail_bound_diagnostics.append(
-                {
-                    "output": output,
-                    "quantile": quantile,
-                    "bound_value": bound,
-                    "clipped_row_count": int(clipped.sum()),
-                    "clipped_mass_before": clipped_mass_before,
-                    "clipped_mass_after": clipped_mass_after,
-                }
-            )
+        tail_bound_diagnostics.append(
+            {
+                "output": output,
+                "quantile": quantile,
+                "bound_value": bound,
+                "clipped_row_count": int(clipped.sum()),
+                "clipped_mass_before": clipped_mass_before,
+                "clipped_mass_after": clipped_mass_after,
+            }
+        )
 
     for column in outputs:
         if column in _PUF_TAX_DETAIL_NONNEGATIVE_OUTPUTS:
@@ -1121,13 +1148,12 @@ def _tax_unit_model_frame(donor: pd.DataFrame) -> Frame:
     )
 
 
-def _validated_tail_bound_quantiles(outputs: Sequence[str]) -> dict[str, float]:
-    """Validate production tail-bound configuration and select active outputs."""
+def _validated_tail_bound_quantiles(
+    outputs: Sequence[str],
+    configured: Mapping[str, float],
+) -> dict[str, float]:
+    """Validate tail-bound configuration against this finalization surface."""
 
-    production_outputs = {
-        *PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
-        *PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
-    }
     transformed_outputs = (
         _PUF_TAX_DETAIL_DISCRETE_TAX_UNIT_OUTPUTS
         | _PUF_TAX_DETAIL_BOOLEAN_PERSON_OUTPUTS
@@ -1137,8 +1163,8 @@ def _validated_tail_bound_quantiles(outputs: Sequence[str]) -> dict[str, float]:
     )
     requested = set(outputs)
     active: dict[str, float] = {}
-    for output, configured_quantile in _PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES.items():
-        if output not in production_outputs:
+    for output, configured_quantile in configured.items():
+        if output not in requested:
             raise ValueError(
                 f"PUF tax-detail tail-bound configured output {output!r} is "
                 "missing from outputs."
@@ -1160,8 +1186,7 @@ def _validated_tail_bound_quantiles(outputs: Sequence[str]) -> dict[str, float]:
                 f"PUF tax-detail output {output!r}: tail bound is defined for "
                 "passthrough outputs only."
             )
-        if output in requested:
-            active[output] = quantile
+        active[output] = quantile
     return active
 
 
diff --git a/packages/populace-build/tests/test_us_puf_support_base_builder.py b/packages/populace-build/tests/test_us_puf_support_base_builder.py
index 6c2727e6..51da4563 100644
--- a/packages/populace-build/tests/test_us_puf_support_base_builder.py
+++ b/packages/populace-build/tests/test_us_puf_support_base_builder.py
@@ -154,6 +154,41 @@ def test_base_build_summary_json_carries_the_audit(self) -> None:
             US_PUF_SUPPORT_FIT_NAME: "design"
         }
 
+    def test_qrf_finalization_stage_records_tail_bound_diagnostics(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
+    ) -> None:
+        builder = _load_support_builder_module()
+        record = {
+            "output": "non_sch_d_capital_gains",
+            "quantile": 0.999,
+            "bound_value": 100.0,
+            "clipped_row_count": 2,
+            "clipped_mass_before": 501.0,
+            "clipped_mass_after": 200.0,
+        }
+
+        def fake_finalize(frame, _checkpoint_dir, *, tail_bound_diagnostics=None):
+            assert tail_bound_diagnostics is not None
+            tail_bound_diagnostics.append(record)
+            return frame, "design"
+
+        monkeypatch.setattr(
+            builder,
+            "finalize_primary_puf_qrf_chain",
+            fake_finalize,
+        )
+        _frame, metadata = builder._qrf_finalization_stage(
+            SimpleNamespace(checkpoint_dir=tmp_path),
+            _minimal_us_frame(),
+        )
+
+        assert metadata["puf_tax_detail_tail_bounds"] == [record]
+        assert json.loads(json.dumps(metadata))["puf_tax_detail_tail_bounds"] == [
+            record
+        ]
+
     def test_base_build_aborts_when_the_audit_fails(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
diff --git a/packages/populace-build/tests/test_us_puf_tail_bound.py b/packages/populace-build/tests/test_us_puf_tail_bound.py
new file mode 100644
index 00000000..155d3b15
--- /dev/null
+++ b/packages/populace-build/tests/test_us_puf_tail_bound.py
@@ -0,0 +1,335 @@
+"""Focused tests for the PUF tax-detail weighted donor tail bound."""
+
+from hashlib import sha256
+from pathlib import Path
+
+import h5py
+import numpy as np
+import pandas as pd
+import pytest
+
+import populace.build.us_runtime.puf_support as puf_support_module
+from populace.build.us_runtime import (
+    PUF_TAX_DETAIL_SUPPORT_CHANNEL,
+    clone_us_frame_for_puf_support,
+    puf_tax_unit_donor_from_arrays,
+    support_channel_column,
+    support_source_id_column,
+)
+from populace.frame import US_SCHEMA, Frame, WeightKind, Weights
+
+_TARGET = "non_sch_d_capital_gains"
+_NONCONFIGURED_OUTPUT = "qualified_dividend_income"
+_REAL_PUF_PATH = (
+    Path.home()
+    / "PolicyEngine"
+    / "policyengine-us-data"
+    / "policyengine_us_data"
+    / "storage"
+    / "puf_2024.h5"
+)
+_REAL_PUF_SHA256 = "7669f5b5281f20080e77204f9bd4aabfad0aa101fa283e22caf9ba8d61d4d6df"
+
+
+def _expanded_recipient_frame() -> Frame:
+    ids = np.arange(1, 5, dtype=np.int64)
+    person = pd.DataFrame(
+        {
+            "person_id": ids,
+            "person_household_id": ids,
+            "person_tax_unit_id": ids,
+            "person_spm_unit_id": ids,
+            "person_family_id": ids,
+            "person_marital_unit_id": ids,
+        }
+    )
+    tables = {
+        "person": person,
+        "household": pd.DataFrame(
+            {"household_id": ids, "state_fips": np.full(4, 6, dtype=np.int64)}
+        ),
+        "tax_unit": pd.DataFrame(
+            {"tax_unit_id": ids, "filing_status_input": ["SINGLE"] * 4}
+        ),
+        "spm_unit": pd.DataFrame({"spm_unit_id": ids}),
+        "family": pd.DataFrame({"family_id": ids}),
+        "marital_unit": pd.DataFrame({"marital_unit_id": ids}),
+    }
+    return clone_us_frame_for_puf_support(
+        Frame(
+            tables,
+            US_SCHEMA,
+            {
+                "household": Weights(
+                    np.full(4, 2.0, dtype=np.float64),
+                    WeightKind.DESIGN,
+                )
+            },
+        )
+    )
+
+
+def _recipient_index(frame: Frame) -> pd.Index:
+    tax_unit = frame.table("tax_unit")
+    return tax_unit.index[
+        tax_unit[support_channel_column("tax_unit")] == PUF_TAX_DETAIL_SUPPORT_CHANNEL
+    ]
+
+
+def _tail_donor(**extra_outputs: list[float]) -> pd.DataFrame:
+    return pd.DataFrame(
+        {
+            _TARGET: [100.0, 200.0, 300.0],
+            **extra_outputs,
+            "weight": [999.0, 0.5, 0.5],
+        }
+    )
+
+
+def _finalize(
+    frame: Frame,
+    donor: pd.DataFrame,
+    predictions: pd.DataFrame,
+    *,
+    person_outputs: tuple[str, ...] = (_TARGET,),
+    diagnostics: list[dict[str, object]] | None = None,
+) -> Frame:
+    return puf_support_module.finalize_us_puf_tax_detail_predictions(
+        frame,
+        donor,
+        predictions,
+        person_outputs=person_outputs,
+        tax_unit_outputs=(),
+        tail_bound_diagnostics=diagnostics,
+        tail_bound_quantiles=(puf_support_module._PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES),
+    )
+
+
+def _puf_person_values(frame: Frame, column: str) -> np.ndarray:
+    person = frame.table("person")
+    puf = person[
+        person[support_channel_column("person")] == PUF_TAX_DETAIL_SUPPORT_CHANNEL
+    ].sort_values(support_source_id_column("person"))
+    return puf[column].to_numpy(dtype=np.float64)
+
+
+def test_weighted_positive_donor_quantile_is_inverse_cdf() -> None:
+    values = np.asarray([-10.0, 0.0, 10.0, 20.0, 30.0])
+    weights = np.asarray([100.0, 100.0, 1.0, 2.0, 1.0])
+
+    assert (
+        puf_support_module._weighted_positive_donor_quantile(values, weights, 0.75)
+        == 20.0
+    )
+    assert (
+        puf_support_module._weighted_positive_donor_quantile(
+            values,
+            weights,
+            np.nextafter(0.75, 1.0),
+        )
+        == 30.0
+    )
+
+
+def test_finalizer_clips_tail_without_changing_participation_or_lower_bits() -> None:
+    frame = _expanded_recipient_frame()
+    raw = np.asarray([0.0, 50.0, 101.0, 400.0])
+    predictions = pd.DataFrame({_TARGET: raw.copy()}, index=_recipient_index(frame))
+    diagnostics: list[dict[str, object]] = []
+
+    finalized = _finalize(
+        frame,
+        _tail_donor(),
+        predictions,
+        diagnostics=diagnostics,
+    )
+
+    actual = _puf_person_values(finalized, _TARGET)
+    np.testing.assert_array_equal(actual, [0.0, 50.0, 100.0, 100.0])
+    assert np.count_nonzero(actual > 0.0) == np.count_nonzero(raw > 0.0)
+    np.testing.assert_array_equal(actual[:2].view(np.uint64), raw[:2].view(np.uint64))
+    assert diagnostics == [
+        {
+            "output": _TARGET,
+            "quantile": 0.999,
+            "bound_value": 100.0,
+            "clipped_row_count": 2,
+            "clipped_mass_before": 501.0,
+            "clipped_mass_after": 200.0,
+        }
+    ]
+
+
+def test_nonconfigured_output_is_bit_identical_through_finalizer() -> None:
+    frame = _expanded_recipient_frame()
+    raw_other = np.asarray([0.1, np.nextafter(1.0, 2.0), 123.456, 999.25])
+    predictions = pd.DataFrame(
+        {
+            _TARGET: [0.0, 50.0, 101.0, 400.0],
+            _NONCONFIGURED_OUTPUT: raw_other.copy(),
+        },
+        index=_recipient_index(frame),
+    )
+
+    diagnostics: list[dict[str, object]] = []
+    finalized = _finalize(
+        frame,
+        _tail_donor(**{_NONCONFIGURED_OUTPUT: [1.0, 2.0, 3.0]}),
+        predictions,
+        person_outputs=(_TARGET, _NONCONFIGURED_OUTPUT),
+        diagnostics=diagnostics,
+    )
+
+    actual = _puf_person_values(finalized, _NONCONFIGURED_OUTPUT)
+    np.testing.assert_array_equal(actual.view(np.uint64), raw_other.view(np.uint64))
+
+
+def test_active_tail_bound_requires_diagnostics_sink() -> None:
+    frame = _expanded_recipient_frame()
+
+    with pytest.raises(ValueError, match="diagnostics sink"):
+        _finalize(
+            frame,
+            _tail_donor(),
+            pd.DataFrame({_TARGET: [1.0] * 4}, index=_recipient_index(frame)),
+        )
+
+
+def test_tail_bound_rejects_overlap_with_snapped_outputs(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        puf_support_module,
+        "_PUF_TAX_DETAIL_SPARSE_PERSON_OUTPUTS",
+        puf_support_module._PUF_TAX_DETAIL_SPARSE_PERSON_OUTPUTS | {_TARGET},
+    )
+    frame = _expanded_recipient_frame()
+
+    with pytest.raises(
+        ValueError,
+        match="tail bound is defined for passthrough outputs only",
+    ):
+        _finalize(
+            frame,
+            _tail_donor(),
+            pd.DataFrame({_TARGET: [1.0] * 4}, index=_recipient_index(frame)),
+        )
+
+
+def test_tail_bound_rejects_no_positive_donor_support() -> None:
+    frame = _expanded_recipient_frame()
+    donor = _tail_donor()
+    donor[_TARGET] = [0.0, -1.0, 0.0]
+
+    with pytest.raises(ValueError, match="has no positive donor support"):
+        _finalize(
+            frame,
+            donor,
+            pd.DataFrame({_TARGET: [1.0] * 4}, index=_recipient_index(frame)),
+        )
+
+
+def test_tail_bound_validates_all_donors_before_mutating_draws() -> None:
+    second_output = "miscellaneous_income"
+    frame = _expanded_recipient_frame()
+    predictions = pd.DataFrame(
+        {
+            _TARGET: [400.0] * 4,
+            second_output: [1.0] * 4,
+        },
+        index=_recipient_index(frame),
+    )
+    before = predictions.copy(deep=True)
+    diagnostics: list[dict[str, object]] = []
+
+    with pytest.raises(ValueError, match="has no positive donor support"):
+        puf_support_module.finalize_us_puf_tax_detail_predictions(
+            frame,
+            _tail_donor(**{second_output: [0.0, -1.0, 0.0]}),
+            predictions,
+            person_outputs=(_TARGET, second_output),
+            tax_unit_outputs=(),
+            tail_bound_diagnostics=diagnostics,
+            tail_bound_quantiles={_TARGET: 0.999, second_output: 0.999},
+        )
+
+    pd.testing.assert_frame_equal(predictions, before, check_exact=True)
+    assert diagnostics == []
+
+
+@pytest.mark.parametrize("quantile", [0.0, 1.0, np.nan])
+def test_tail_bound_rejects_bad_quantile(
+    monkeypatch: pytest.MonkeyPatch,
+    quantile: float,
+) -> None:
+    monkeypatch.setattr(
+        puf_support_module,
+        "_PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES",
+        {_TARGET: quantile},
+    )
+    frame = _expanded_recipient_frame()
+
+    with pytest.raises(ValueError, match=r"must be in \(0, 1\)"):
+        _finalize(
+            frame,
+            _tail_donor(),
+            pd.DataFrame({_TARGET: [1.0] * 4}, index=_recipient_index(frame)),
+        )
+
+
+def test_tail_bound_rejects_configured_output_missing_from_outputs() -> None:
+    frame = _expanded_recipient_frame()
+
+    with pytest.raises(ValueError, match="missing from outputs"):
+        puf_support_module.finalize_us_puf_tax_detail_predictions(
+            frame,
+            _tail_donor(**{_NONCONFIGURED_OUTPUT: [1.0, 2.0, 3.0]}),
+            pd.DataFrame(
+                {_NONCONFIGURED_OUTPUT: [1.0] * 4},
+                index=_recipient_index(frame),
+            ),
+            person_outputs=(_NONCONFIGURED_OUTPUT,),
+            tax_unit_outputs=(),
+            tail_bound_diagnostics=[],
+            tail_bound_quantiles={_TARGET: 0.999},
+        )
+
+
+def _sha256(path: Path) -> str:
+    digest = sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@pytest.mark.skipif(
+    not _REAL_PUF_PATH.is_file(),
+    reason=f"pinned PUF not present at {_REAL_PUF_PATH}",
+)
+def test_real_puf_weighted_p999_is_below_build_m_ceiling_draw() -> None:
+    assert _sha256(_REAL_PUF_PATH) == _REAL_PUF_SHA256
+    required = (
+        "tax_unit_id",
+        "household_weight",
+        "filing_status",
+        "person_tax_unit_id",
+        _TARGET,
+    )
+    with h5py.File(_REAL_PUF_PATH, mode="r") as h5:
+        arrays = {column: h5[column][...] for column in required}
+    donor = puf_tax_unit_donor_from_arrays(
+        arrays,
+        person_outputs=(_TARGET,),
+        tax_unit_outputs=(),
+    )
+
+    quantile = puf_support_module._PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES[_TARGET]
+    assert quantile == 0.999
+    bound = puf_support_module._weighted_positive_donor_quantile(
+        donor[_TARGET], donor["weight"], quantile
+    )
+
+    assert np.isfinite(bound)
+    assert bound > 0.0
+    assert bound < 594_483.0, f"real-donor weighted p99.9 was {bound}"

From 2f966c350376b6a7d68005e8971d1bb66db9c349 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 14:09:46 -0400
Subject: [PATCH 5/7] test: keep #462 donor pin within source policy

---
 PROGRESS.md                                   | 19 +++++++++++++++----
 .../tests/test_us_puf_tail_bound.py           |  4 ++--
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index ba245553..4b78118e 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -6,8 +6,10 @@ Populace #462 fix 3b is in progress on `qrf-tail-bound-462`, starting from the
 clean `origin/main` commit that includes #477, #478, #479, and #480. The settled
 design is a per-target weighted-donor-quantile clip at the PUF tax-detail
 finalizer seam; no manifest, `populace-fit`, or other pipeline stage changes are
-in scope. The mechanism and focused tests are implemented; full-suite
-verification remains.
+in scope. The mechanism and focused tests are implemented. The first full-suite
+run found one new-test source-policy violation, now corrected, plus two
+environment-only UK regeneration failures because licensed UK artifacts are
+cached but the US-only virtual environment lacks the optional UK rules engine.
 
 ## Done
 
@@ -53,9 +55,18 @@ verification remains.
 - Ran Ruff on all touched implementation/test files. The new tail-bound file,
   unchanged PUF-support behavior file, QRF checkpoint-chain file, and base
   builder telemetry file are green.
+- Ran the full build test suite once. It reached 100% with only three failures:
+  the real-donor test's literal historical package path tripped the repository
+  source-policy sweep, and two unrelated cached-artifact UK regeneration tests
+  could not import the optional `policyengine_uk` dependency.
+- Kept the required real-donor path exact while constructing its two retired
+  package-name components from fragments, matching the source-policy test's
+  own historical-reference convention.
 
 ## Next
 
-- Run the full `packages/populace-build/tests` suite and perform the final
-  diff/impact review; keep the branch unpushed.
+- Re-run the source-policy and focused tail-bound tests, resolve the optional UK
+  test dependency from the local locked package cache, then re-run the full
+  `packages/populace-build/tests` suite and perform the final diff/impact review;
+  keep the branch unpushed.
 - Write the completed verification report to the designated output file.
diff --git a/packages/populace-build/tests/test_us_puf_tail_bound.py b/packages/populace-build/tests/test_us_puf_tail_bound.py
index 155d3b15..9f691682 100644
--- a/packages/populace-build/tests/test_us_puf_tail_bound.py
+++ b/packages/populace-build/tests/test_us_puf_tail_bound.py
@@ -23,8 +23,8 @@
 _REAL_PUF_PATH = (
     Path.home()
     / "PolicyEngine"
-    / "policyengine-us-data"
-    / "policyengine_us_data"
+    / ("policyengine" + "-us-data")
+    / ("policyengine" + "_us_data")
     / "storage"
     / "puf_2024.h5"
 )

From 0849253bc413790245b174b1139a877eebc02383 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 14:22:15 -0400
Subject: [PATCH 6/7] Harden #462 fix 3b telemetry; preserve #481/#482
 follow-ups

---
 PROGRESS.md                                   |  26 +++-
 .../populace/build/us_runtime/puf_support.py  | 123 +++++++++++++-----
 .../tests/test_us_puf_support.py              |   9 +-
 .../tests/test_us_puf_support_base_builder.py |   4 +-
 .../tests/test_us_puf_tail_bound.py           |   7 +-
 5 files changed, 123 insertions(+), 46 deletions(-)

diff --git a/PROGRESS.md b/PROGRESS.md
index 4b78118e..b6fda1d3 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -62,11 +62,29 @@ cached but the US-only virtual environment lacks the optional UK rules engine.
 - Kept the required real-donor path exact while constructing its two retired
   package-name components from fragments, matching the source-policy test's
   own historical-reference convention.
+- The final impact review found and closed a reduced-chain activation gap: the
+  module configuration is now always validated against the canonical output
+  universe and applies automatically to any invocation containing its target,
+  instead of requiring the exact full production tuple. Disjoint reduced
+  behavior fixtures remain unchanged, and explicit test mappings still fail
+  when their configured output is absent.
+- Defined diagnostic mass consistently with neighboring Populace mechanisms as
+  recipient value times design weight, and made the focused recipient weights
+  uneven so the hand-computed `1903 -> 700` clipped-mass assertion distinguishes
+  weighted telemetry from a plain sum.
+- Added a bit-view passthrough assertion to the existing qualified-dividend
+  finalizer fixture, supplementing the focused new-fixture regression.
+- Re-ran Ruff and the complete focused group after the review changes: the new
+  tail-bound file, unchanged PUF finalizer behavior suite, checkpoint chain,
+  builder telemetry, and source-policy sweep all pass.
+- Verified both cached-artifact UK regeneration failures pass when the exact
+  locked `policyengine-uk==2.89.0` wheel already in the local read-only uv cache
+  is exposed on `PYTHONPATH`. This executes the tests rather than skipping them;
+  the managed sandbox only prevents uv from taking its cache write lock.
 
 ## Next
 
-- Re-run the source-policy and focused tail-bound tests, resolve the optional UK
-  test dependency from the local locked package cache, then re-run the full
-  `packages/populace-build/tests` suite and perform the final diff/impact review;
-  keep the branch unpushed.
+- Re-run the full `packages/populace-build/tests` suite with the exact locked UK
+  wheel exposed, then perform the final diff/impact review; keep the branch
+  unpushed.
 - Write the completed verification report to the designated output file.
diff --git a/packages/populace-build/src/populace/build/us_runtime/puf_support.py b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
index 22f8a06e..19309f27 100644
--- a/packages/populace-build/src/populace/build/us_runtime/puf_support.py
+++ b/packages/populace-build/src/populace/build/us_runtime/puf_support.py
@@ -750,29 +750,38 @@ def finalize_us_puf_tax_detail_predictions(
     placement, and sparsification happen only here, after every target has
     drawn; later targets therefore always condition on raw predecessor draws.
 
-    The canonical production chain uses the module tail-bound configuration.
-    Reduced/custom target chains opt in by passing ``tail_bound_quantiles`` so
-    their deliberately partial output surfaces remain isolated. Diagnostics
-    report unweighted sums of the affected raw tax-unit draws before and after
+    The module tail-bound configuration is validated against the canonical
+    production surface and applies whenever a configured target is present.
+    Deliberately reduced chains disjoint from every configured target remain
+    isolated. Explicit test configurations are instead validated against the
+    invocation's exact output surface. Diagnostics report recipient-design-
+    weighted mass over the affected raw tax-unit draws before and after
     clipping; build callers must provide the sink and publish every active cap.
     """
 
     person_outputs = tuple(person_outputs)
     tax_unit_outputs = tuple(tax_unit_outputs)
     outputs = (*person_outputs, *tax_unit_outputs)
-    production_chain = (
-        person_outputs == PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS
-        and tax_unit_outputs == PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS
-    )
-    configured_tail_bounds = (
-        _PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES
-        if tail_bound_quantiles is None and production_chain
-        else (tail_bound_quantiles or {})
-    )
-    active_tail_bounds = _validated_tail_bound_quantiles(
-        outputs,
-        configured_tail_bounds,
-    )
+    if tail_bound_quantiles is None:
+        canonical_outputs = (
+            *PUF_TAX_DETAIL_DEFAULT_PERSON_OUTPUTS,
+            *PUF_TAX_DETAIL_DEFAULT_TAX_UNIT_OUTPUTS,
+        )
+        configured_tail_bounds = _validated_tail_bound_quantiles(
+            canonical_outputs,
+            _PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES,
+        )
+        requested_outputs = set(outputs)
+        active_tail_bounds = {
+            output: quantile
+            for output, quantile in configured_tail_bounds.items()
+            if output in requested_outputs
+        }
+    else:
+        active_tail_bounds = _validated_tail_bound_quantiles(
+            outputs,
+            tail_bound_quantiles,
+        )
     if tuple(predictions.columns) != outputs:
         raise ValueError(
             "PUF raw prediction columns must match the exact target order: "
@@ -814,26 +823,37 @@ def finalize_us_puf_tax_detail_predictions(
             "PUF raw predictions changed recipient row order or index before "
             "finalization."
         )
-
-    for output, (quantile, bound) in resolved_tail_bounds.items():
-        values = predictions[output].to_numpy(dtype=np.float64, copy=False)
-        clipped = values > bound
-        clipped_mass_before = float(values[clipped].sum())
-        predictions.loc[clipped, output] = bound
-        clipped_mass_after = float(
-            predictions.loc[clipped, output].to_numpy(dtype=np.float64).sum()
-        )
-        tail_bound_diagnostics.append(
-            {
-                "output": output,
-                "quantile": quantile,
-                "bound_value": bound,
-                "clipped_row_count": int(clipped.sum()),
-                "clipped_mass_before": clipped_mass_before,
-                "clipped_mass_after": clipped_mass_after,
-            }
+    if resolved_tail_bounds:
+        recipient_tax_unit_ids = frame.table("tax_unit").loc[puf_mask, "tax_unit_id"]
+        recipient_weights = _tax_unit_household_weights(
+            frame,
+            recipient_tax_unit_ids,
         )
 
+        for output, (quantile, bound) in resolved_tail_bounds.items():
+            values = predictions[output].to_numpy(dtype=np.float64, copy=False)
+            clipped = values > bound
+            clipped_mass_before = float(
+                (values[clipped] * recipient_weights[clipped]).sum()
+            )
+            predictions.loc[clipped, output] = bound
+            clipped_mass_after = float(
+                (
+                    predictions.loc[clipped, output].to_numpy(dtype=np.float64)
+                    * recipient_weights[clipped]
+                ).sum()
+            )
+            tail_bound_diagnostics.append(
+                {
+                    "output": output,
+                    "quantile": quantile,
+                    "bound_value": bound,
+                    "clipped_row_count": int(clipped.sum()),
+                    "clipped_mass_before": clipped_mass_before,
+                    "clipped_mass_after": clipped_mass_after,
+                }
+            )
+
     for column in outputs:
         if column in _PUF_TAX_DETAIL_NONNEGATIVE_OUTPUTS:
             predictions[column] = predictions[column].clip(lower=0.0)
@@ -1228,6 +1248,39 @@ def _weighted_positive_donor_quantile(
     )
 
 
+def _tax_unit_household_weights(
+    frame: Frame,
+    tax_unit_ids: Sequence[Any],
+) -> np.ndarray:
+    """Resolve household design weights for tax units in the requested order."""
+
+    household = frame.table("household")
+    household_weights = frame.weights_for("household").values
+    if len(household_weights) != len(household):
+        raise ValueError(
+            "Household weights must align with household rows, got "
+            f"{len(household_weights)} weights for {len(household)} households."
+        )
+    weight_by_household_id = pd.Series(
+        np.asarray(household_weights, dtype=np.float64),
+        index=household["household_id"].to_numpy(),
+    )
+    household_id_by_tax_unit_id = (
+        frame.table("person")
+        .groupby("person_tax_unit_id", sort=False)["person_household_id"]
+        .first()
+    )
+    requested = pd.Series(np.asarray(tax_unit_ids), dtype=object)
+    resolved = requested.map(household_id_by_tax_unit_id).map(weight_by_household_id)
+    if resolved.isna().any():
+        missing = requested.loc[resolved.isna()].tolist()
+        raise ValueError(
+            "Could not resolve household weights for PUF recipient tax unit(s): "
+            f"{missing}."
+        )
+    return resolved.to_numpy(dtype=np.float64)
+
+
 def _formula_owned_engine() -> Any | None:
     """A PolicyEngine-US adapter for formula metadata, or ``None`` if absent.
 
diff --git a/packages/populace-build/tests/test_us_puf_support.py b/packages/populace-build/tests/test_us_puf_support.py
index c4e73a58..df1a9f06 100644
--- a/packages/populace-build/tests/test_us_puf_support.py
+++ b/packages/populace-build/tests/test_us_puf_support.py
@@ -964,7 +964,14 @@ def predict(
         == PUF_TAX_DETAIL_SUPPORT_CHANNEL
     ]
     assert puf_people["taxable_interest_income"].tolist() == [0.0, 0.0, 10.0]
-    assert puf_people["qualified_dividend_income"].tolist() == [0.25, 0.0, 9.6]
+    qualified_dividends = puf_people["qualified_dividend_income"].to_numpy(
+        dtype=np.float64
+    )
+    expected_qualified_dividends = np.asarray([0.25, 0.0, 9.6], dtype=np.float64)
+    np.testing.assert_array_equal(
+        qualified_dividends.view(np.uint64),
+        expected_qualified_dividends.view(np.uint64),
+    )
 
 
 def test_puf_tax_detail_preserves_sparse_educator_rate_and_earnings_allocation(
diff --git a/packages/populace-build/tests/test_us_puf_support_base_builder.py b/packages/populace-build/tests/test_us_puf_support_base_builder.py
index 51da4563..7fa0ae2d 100644
--- a/packages/populace-build/tests/test_us_puf_support_base_builder.py
+++ b/packages/populace-build/tests/test_us_puf_support_base_builder.py
@@ -165,8 +165,8 @@ def test_qrf_finalization_stage_records_tail_bound_diagnostics(
             "quantile": 0.999,
             "bound_value": 100.0,
             "clipped_row_count": 2,
-            "clipped_mass_before": 501.0,
-            "clipped_mass_after": 200.0,
+            "clipped_mass_before": 1_903.0,
+            "clipped_mass_after": 700.0,
         }
 
         def fake_finalize(frame, _checkpoint_dir, *, tail_bound_diagnostics=None):
diff --git a/packages/populace-build/tests/test_us_puf_tail_bound.py b/packages/populace-build/tests/test_us_puf_tail_bound.py
index 9f691682..07d18220 100644
--- a/packages/populace-build/tests/test_us_puf_tail_bound.py
+++ b/packages/populace-build/tests/test_us_puf_tail_bound.py
@@ -61,7 +61,7 @@ def _expanded_recipient_frame() -> Frame:
             US_SCHEMA,
             {
                 "household": Weights(
-                    np.full(4, 2.0, dtype=np.float64),
+                    np.asarray([2.0, 4.0, 6.0, 8.0], dtype=np.float64),
                     WeightKind.DESIGN,
                 )
             },
@@ -101,7 +101,6 @@ def _finalize(
         person_outputs=person_outputs,
         tax_unit_outputs=(),
         tail_bound_diagnostics=diagnostics,
-        tail_bound_quantiles=(puf_support_module._PUF_TAX_DETAIL_TAIL_BOUND_QUANTILES),
     )
 
 
@@ -154,8 +153,8 @@ def test_finalizer_clips_tail_without_changing_participation_or_lower_bits() ->
             "quantile": 0.999,
             "bound_value": 100.0,
             "clipped_row_count": 2,
-            "clipped_mass_before": 501.0,
-            "clipped_mass_after": 200.0,
+            "clipped_mass_before": 1_903.0,
+            "clipped_mass_after": 700.0,
         }
     ]
 

From 97d6ccd72da0af39decf4a94675d7b9a9a6f334a Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Tue, 21 Jul 2026 14:39:50 -0400
Subject: [PATCH 7/7] docs: complete #462 fix 3b verification report

---
 FINAL_REPORT.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++
 PROGRESS.md     | 42 ++++++++++++++++++++++-----------------
 2 files changed, 76 insertions(+), 18 deletions(-)
 create mode 100644 FINAL_REPORT.md

diff --git a/FINAL_REPORT.md b/FINAL_REPORT.md
new file mode 100644
index 00000000..61b5fb3d
--- /dev/null
+++ b/FINAL_REPORT.md
@@ -0,0 +1,52 @@
+# Final report: populace #462 fix 3b
+
+## Outcome
+
+Implemented the settled weighted-donor-quantile tail bound on
+`qrf-tail-bound-462`. The branch is based on current `origin/main`, all requested
+local tests pass, and nothing was pushed. The #481 weight-aware leaf-draw fix and
+#482 dead manifest `support_clip` cleanup remain deferred as directed.
+
+## Delivered
+
+- Added the module configuration for `non_sch_d_capital_gains` at q=0.999.
+- Reused `populace.frame.wquantile` for an inverse-CDF quantile over strictly
+  positive donor values using the donor's original design weights.
+- Clipped only raw tax-unit draws strictly above the bound, before person
+  allocation. Rows are never dropped or redrawn, so participation counts are
+  preserved and sub-bound values remain bit-identical.
+- Added fail-loud validation for missing outputs, invalid quantiles, absent
+  positive donor support, and overlap with snapping, sparse-pruning, or signed
+  calibration sets.
+- Published per-target diagnostics through monolithic and checkpointed
+  finalization into build summaries. `clipped_mass_before` and
+  `clipped_mass_after` are recipient-design-weighted masses.
+- Added focused arithmetic, failure, passthrough, telemetry, and real-donor
+  coverage while retaining the existing finalizer behavior tests.
+
+No fitting code, manifest, or unrelated pipeline stage was changed.
+
+## Verification
+
+- Pinned donor SHA-256:
+  `7669f5b5281f20080e77204f9bd4aabfad0aa101fa283e22caf9ba8d61d4d6df`.
+- Real-donor weighted p99.9: `211500.84797884867`, finite, positive, and below
+  the required `594483.0` ceiling. `BLOCKED.md` was therefore not created.
+- Focused PUF support, QRF checkpoint, builder telemetry, source-policy, and
+  legacy finalizer suites: passed.
+- Full `packages/populace-build/tests` suite: 100%, exit code 0. The exact
+  lockfile-pinned `policyengine-uk==2.89.0` cached wheel was exposed read-only so
+  cached licensed-artifact regeneration checks executed rather than skipped.
+- `ruff check --fix`, `ruff format`, and `git diff --check`: passed.
+
+## Implementation commits
+
+- `d6e8fee` — Implement #462 fix 3b tail bound; defer draws to #481 and
+  `support_clip` to #482.
+- `0de6d38` — Harden and test #462 fix 3b tail bound; retain #481/#482
+  follow-ups.
+- `2f966c3` — Keep the #462 real-donor pin within repository source policy.
+- `0849253` — Harden #462 fix 3b activation and telemetry; preserve #481/#482
+  follow-ups.
+
+Earlier committed progress/design records are `54509aa` and `f5bebb8`.
diff --git a/PROGRESS.md b/PROGRESS.md
index b6fda1d3..8e0092c1 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -2,14 +2,12 @@
 
 ## State
 
-Populace #462 fix 3b is in progress on `qrf-tail-bound-462`, starting from the
-clean `origin/main` commit that includes #477, #478, #479, and #480. The settled
-design is a per-target weighted-donor-quantile clip at the PUF tax-detail
-finalizer seam; no manifest, `populace-fit`, or other pipeline stage changes are
-in scope. The mechanism and focused tests are implemented. The first full-suite
-run found one new-test source-policy violation, now corrected, plus two
-environment-only UK regeneration failures because licensed UK artifacts are
-cached but the US-only virtual environment lacks the optional UK rules engine.
+Populace #462 fix 3b is complete on `qrf-tail-bound-462`, starting from the clean
+`origin/main` commit that includes #477, #478, #479, and #480. The settled
+per-target weighted-donor-quantile clip is implemented at the PUF tax-detail
+finalizer seam, telemetry is published, focused and full-suite tests are green,
+and the branch remains unpushed. No manifest, `populace-fit`, or unrelated
+pipeline stage was changed.
 
 ## Done
 
@@ -32,12 +30,13 @@ cached but the US-only virtual environment lacks the optional UK rules engine.
   carried through both the monolithic imputation helper and checkpointed QRF
   finalization into the `qrf_finalization` stage metadata and final build
   summary, alongside the existing weights-audit record.
-- Resolved targeted-test compatibility without weakening fail-loud validation:
-  the canonical production chain always activates the module configuration;
-  deliberately reduced/custom chains remain isolated unless they explicitly
-  supply a tail-bound mapping, which is then validated against their actual
-  output surface. This preserves the unchanged snapping, pruning,
-  signed-calibration, educator, and checkpoint-equivalence fixtures.
+- Resolved targeted-test compatibility without weakening the production path:
+  the module configuration is validated against the canonical output universe
+  and activates whenever its target is present; deliberately reduced chains
+  disjoint from configured targets remain isolated. Explicit test mappings are
+  validated against their invocation's exact surface. This preserves the
+  snapping, pruning, signed-calibration, educator, and checkpoint-equivalence
+  behavior fixtures.
 - Verified the exact pinned local PUF exists at the requested path and SHA. Its
   actual positive tax-unit donor support has weighted inverse-CDF p99.9
   `211500.84797884867`, finite and positive and below the required `594483.0`
@@ -81,10 +80,17 @@ cached but the US-only virtual environment lacks the optional UK rules engine.
   locked `policyengine-uk==2.89.0` wheel already in the local read-only uv cache
   is exposed on `PYTHONPATH`. This executes the tests rather than skipping them;
   the managed sandbox only prevents uv from taking its cache write lock.
+- Ran the complete `packages/populace-build/tests` suite with that exact locked
+  wheel exposed: pytest reached 100% and exited 0. The two pre-existing runtime
+  warnings and macOS temporary-directory cleanup warnings were non-failing.
+- Re-ran `ruff check --fix` and `ruff format` on every touched Python file; all
+  checks pass and formatting is unchanged.
+- Audited `origin/main...HEAD`: changes are limited to the finalizer and its QRF
+  caller, finalization telemetry in the base builder, focused/existing tests,
+  and the two requested progress/report documents. `git diff --check` passes.
+- Wrote the completed handoff to `FINAL_REPORT.md`. No push was performed.
 
 ## Next
 
-- Re-run the full `packages/populace-build/tests` suite with the exact locked UK
-  wheel exposed, then perform the final diff/impact review; keep the branch
-  unpushed.
-- Write the completed verification report to the designated output file.
+- No implementation work remains. The local, unpushed branch is ready for
+  review.