Recertify a published US release for a newer policyengine-us without a rebuild

README.md

@@ -348,6 +348,14 @@ type publishes the [reported-receipt child of the national default](docs/us-repo
 as a tag-only donor for the ACS local chain. It is never the `latest.json`
 default.
 
+A [compatibility recertification](docs/us-compatibility-recertification.md)
+republishes a published US calibration release byte for byte under a new id,
+with a measured `compatible_model_packages` claim for a newer policyengine-us:
+a loader replay under the tested country, Core and calculator wheels, the engine's reviewed column
+changes, and the drift of the critical rows and headline totals between the
+built-with and tested engines. It never recalibrates. Publication refuses a
+child whose parent tag on the Hub does not serve the carried manifest bytes.
+
 The non-default ACS local-area chain (`tools/build_us_acs_local_release.py`)
 calibrates to the SOI `state` surface by default, the 4,459-target contract of
 Build O and Build P; `--soi-mode totals` and `--soi-mode full` are explicit

changelog.d/us-compatibility-recertification.added.md

@@ -0,0 +1 @@
+Add the `compatibility_recertification` release type: a published US calibration release republished byte for byte with a measured `compatible_model_packages` claim for a newer policyengine-us. It carries the parent's published manifests as its identity, replays the country loader under the tested country, Core and calculator wheels (compiled from verified source into an isolated bytecode cache), records the engine's reviewed column changes in both directions, and embeds the drift of the critical rows and headline totals between the built-with and tested engines. Publication refuses a child whose parent tag does not serve the carried manifest bytes. `tools/build_us_compatibility_recertification.py` fetches the parent, builds the candidate and scores it; see `docs/us-compatibility-recertification.md`.

docs/agent-guide.md

@@ -305,6 +305,18 @@ against both H5 files. The publisher refuses to point `latest.json` at this
 child, so publish it with `--no-latest --tag-only`. See
 [the reported-receipt runbook](us-reported-receipt-source-enrichment.md).
 
+`compatibility_recertification` is a separate release type
+(`microcosm.data.compatibility_recertification`,
+`tools/build_us_compatibility_recertification.py`): a published US
+calibration release, republished byte for byte with a measured claim for a
+newer policyengine-us. Its parent identity is the parent's own published
+`release_manifest.json`, carried and hashed, never a code constant; the
+publisher checks the parent tag on the Hub before any upload. A change in
+what the tested engine reads or ignores must have an entry in
+`RECERTIFICATION_COLUMN_CHANGES`. It takes `--compatibility-wheel` and no
+`--parent-h5`. National parents only for now. See
+[the recertification runbook](us-compatibility-recertification.md).
+
 Three US release seams refuse a stored column that is lowercase snake_case,
 not a variable of the engine the release is certified against, and not in the
 reviewed register `microcosm.data.stored_inputs.US_STORED_NON_VARIABLE_COLUMNS`

packages/microcosm-build/tests/engine_free/us/test_us_compatibility_recertification_parity.py

@@ -0,0 +1,67 @@
+"""The recertification scorer copies two release-tool rules; hold them equal.
+
+``microcosm.data.compatibility_recertification`` scores SOI rows with the
+release tool's signed-component rule and refuses the release tool's
+population-aggregate formulas in batch engines. The data shard cannot import
+the tool, so it carries copies, and these tests are what keeps them the
+tool's.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from microcosm.data import compatibility_recertification as recert
+from test_support.microcosm_build.us_post_export_scoring import _load_builder_module
+
+
+@pytest.fixture(scope="module")
+def release_tool():
+    return _load_builder_module()
+
+
+def test_population_aggregate_variables_are_the_release_tools(release_tool):
+    assert recert.POPULATION_AGGREGATE_VARIABLES == (
+        release_tool.US_POPULATION_AGGREGATE_VARIABLES
+    )
+    assert set(recert.STATE_AGGREGATE_VARIABLES) <= set(
+        release_tool.US_POPULATION_AGGREGATE_VARIABLES
+    )
+
+
+_SOURCES = sorted(
+    {
+        "adjusted_gross_income",
+        "rent_and_royalty_net_income",
+        "capital_gains_losses",
+        "business_net_losses",
+        "estate_losses",
+        "partnership_and_s_corp_losses",
+        "rent_and_royalty_net_losses",
+        "miscellaneous_losses",
+        "income_tax",
+        "eitc",
+        "ctc",
+        "employment_income",
+        "taxable_social_security",
+    }
+)
+
+
+@settings(max_examples=300, deadline=None)
+@given(
+    values=st.lists(
+        st.floats(-1e12, 1e12, allow_nan=False, allow_infinity=False),
+        min_size=1,
+        max_size=16,
+    ),
+    source=st.sampled_from(_SOURCES),
+)
+def test_signed_component_is_the_release_tools(release_tool, values, source):
+    np.testing.assert_array_equal(
+        recert.signed_component(values, source),
+        release_tool._signed_component(np.asarray(values), source),
+    )