From df46de301fbb10b9b048a293d874e53feddc06d8 Mon Sep 17 00:00:00 2001 From: desp0042 Date: Thu, 30 Jul 2026 07:51:31 +0200 Subject: [PATCH 1/5] release: prove installed-wheel component packages --- scripts/final_release_contract.py | 4 +++ scripts/release_preflight.py | 52 ++++++++++++++++++++++++++++++- scripts/run_final_gate.py | 35 +++++++++++++++++++-- 3 files changed, 88 insertions(+), 3 deletions(-) diff --git a/scripts/final_release_contract.py b/scripts/final_release_contract.py index 39658bcde..85c7e7b8d 100644 --- a/scripts/final_release_contract.py +++ b/scripts/final_release_contract.py @@ -35,6 +35,10 @@ # The published wheel matrix is CPU/Kokkos Serial without MPI or parallel HDF5. The full suite still # runs; this supported-platform subset is repeated with a strict all-pass/no-hidden-skip policy. PYTHON_REQUIRED_SELECTION = "not mpi and not hdf5" +INSTALLED_COMPONENT_PACKAGE_NODEID = ( + "tests/python/integration/native_loader/test_external_component_package.py" + "::test_source_component_executes_through_generic_native_loader_and_flux_consumer" +) REQUIRED_RELEASE_GATES = ( "official_build", "installed_wheel", diff --git a/scripts/release_preflight.py b/scripts/release_preflight.py index 57820f96c..6b4993dde 100644 --- a/scripts/release_preflight.py +++ b/scripts/release_preflight.py @@ -21,6 +21,7 @@ from final_release_contract import ( FINAL_EXAMPLES, + INSTALLED_COMPONENT_PACKAGE_NODEID, PYTHON_REQUIRED_SELECTION, REQUIRED_PROOF_MARKERS, REQUIRED_RELEASE_GATES, @@ -485,7 +486,7 @@ def _evidence(path: Path, contract: Any, commit: str, runtime: dict[str, str]) - for name in ("native_conformance", "python_conformance"): evidence = gates[name]["evidence"] expected = {"required_lane"} if name == "native_conformance" \ - else {"required_lane", "selection"} + else {"required_lane", "selection", "installed_component_package"} if not isinstance(evidence, dict) or set(evidence) != expected: raise PreflightError("release evidence %s lane is malformed" % name) lane = evidence["required_lane"] @@ -502,6 +503,55 @@ def _evidence(path: Path, contract: Any, commit: str, runtime: dict[str, str]) - label="%s JUnit" % name) if gates["python_conformance"]["evidence"]["selection"] != PYTHON_REQUIRED_SELECTION: raise PreflightError("release evidence Python required-lane selection drifted") + component = gates["python_conformance"]["evidence"]["installed_component_package"] + if not isinstance(component, dict) or set(component) != {"nodeid", "headers", "lane"}: + raise PreflightError("release evidence installed component package lane is malformed") + if component["nodeid"] != INSTALLED_COMPONENT_PACKAGE_NODEID \ + or component["headers"] != "installed-wheel": + raise PreflightError("release evidence installed component package authority drifted") + lane = component["lane"] + if not isinstance(lane, dict) or set(lane) != { + "path", "sha256", "tests", "failures", "skips_or_xfails"}: + raise PreflightError("release evidence installed component package JUnit is malformed") + if lane["tests"] != 1 or lane["failures"] != 0 or lane["skips_or_xfails"] != 0: + raise PreflightError("release evidence installed component package lane is not all-pass") + component_report = Path(lane["path"]).resolve() + if not _inside(directory, component_report): + raise PreflightError( + "release evidence installed component package JUnit path escapes its directory") + _artifact_file( + directory, + component_report.relative_to(directory), + lane["sha256"], + label="installed component package JUnit", + ) + component_commands = [ + command for command in gates["python_conformance"]["commands"] + if INSTALLED_COMPONENT_PACKAGE_NODEID in command["argv"] + ] + if len(component_commands) != 1: + raise PreflightError( + "release evidence must execute the installed component package node exactly once") + component_argv = component_commands[0]["argv"] + include_assignments = [ + argument for argument in component_argv if argument.startswith("POPS_INCLUDE=") + ] + if include_assignments != ["POPS_INCLUDE="] \ + or "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1" not in component_argv: + raise PreflightError( + "installed component package proof must use only wheel-owned headers") + expected_suffix = [ + "python", + "-m", + "pytest", + "-q", + "-s", + INSTALLED_COMPONENT_PACKAGE_NODEID, + "--junitxml", + lane["path"], + ] + if component_argv[-len(expected_suffix):] != expected_suffix: + raise PreflightError("installed component package proof command drifted") _examples_evidence(directory, gates, runtime) diff --git a/scripts/run_final_gate.py b/scripts/run_final_gate.py index 0fbbbf2bc..61de40157 100644 --- a/scripts/run_final_gate.py +++ b/scripts/run_final_gate.py @@ -29,6 +29,7 @@ from final_release_contract import ( FINAL_EXAMPLES, FINAL_SPECIFICATION, + INSTALLED_COMPONENT_PACKAGE_NODEID, PYTHON_REQUIRED_SELECTION, REQUIRED_PROOF_MARKERS, REQUIRED_RELEASE_GATES, @@ -93,7 +94,11 @@ def _outside_checkout(path: Path) -> Path: raise FinalGateError("--evidence must be outside the checkout: %s" % resolved) -def _conda_command(arguments: Sequence[str]) -> list[str]: +def _conda_command( + arguments: Sequence[str], + *, + pops_include: Path | None = ROOT / "include", +) -> list[str]: """Run inside the same conda installation selected by the gate process. A login shell is deliberately forbidden here: user startup files may rewrite ``PATH`` and @@ -142,7 +147,7 @@ def _conda_command(arguments: Sequence[str]) -> list[str]: "PYTHONPATH=", "PYTHONNOUSERSITE=1", "POPS_REQUIRE_NATIVE_TESTS=1", - "POPS_INCLUDE=" + str((ROOT / "include").resolve()), + "POPS_INCLUDE=" + ("" if pops_include is None else str(pops_include.resolve())), *arguments, ] @@ -558,9 +563,35 @@ def main(argv: Sequence[str] | None = None) -> int: "--junitxml", str(python_junit), ])) _require_no_hidden_skip(required_stdout) + installed_component_junit = ( + evidence_root / "reports" / "installed-component-package.xml" + ) + installed_component_stdout = recorder.run( + "python_conformance", + _conda_command( + [ + "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1", + "python", + "-m", + "pytest", + "-q", + "-s", + INSTALLED_COMPONENT_PACKAGE_NODEID, + "--junitxml", + str(installed_component_junit), + ], + pops_include=None, + ), + ) + _require_no_hidden_skip(installed_component_stdout) recorder.rows["python_conformance"]["evidence"] = { "required_lane": _junit_summary(python_junit), "selection": PYTHON_REQUIRED_SELECTION, + "installed_component_package": { + "nodeid": INSTALLED_COMPONENT_PACKAGE_NODEID, + "headers": "installed-wheel", + "lane": _junit_summary(installed_component_junit), + }, } signed_runtime_sha256 = _signed_runtime_sha256( recorder.rows["codesign"]["evidence"]) From 90354cfec1e2f86b73d047c40f4514592e6407ba Mon Sep 17 00:00:00 2001 From: desp0042 Date: Thu, 30 Jul 2026 07:53:35 +0200 Subject: [PATCH 2/5] release: isolate component package evidence audit --- scripts/release_preflight.py | 105 +++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 49 deletions(-) diff --git a/scripts/release_preflight.py b/scripts/release_preflight.py index 6b4993dde..c4771bf84 100644 --- a/scripts/release_preflight.py +++ b/scripts/release_preflight.py @@ -438,6 +438,61 @@ def _examples_evidence( raise PreflightError("release evidence restart proof markers drifted for %s" % key) +def _installed_component_package_evidence( + directory: Path, + python_conformance: dict[str, Any], +) -> None: + component = python_conformance["evidence"]["installed_component_package"] + if not isinstance(component, dict) or set(component) != {"nodeid", "headers", "lane"}: + raise PreflightError("release evidence installed component package lane is malformed") + if component["nodeid"] != INSTALLED_COMPONENT_PACKAGE_NODEID \ + or component["headers"] != "installed-wheel": + raise PreflightError("release evidence installed component package authority drifted") + lane = component["lane"] + if not isinstance(lane, dict) or set(lane) != { + "path", "sha256", "tests", "failures", "skips_or_xfails"}: + raise PreflightError("release evidence installed component package JUnit is malformed") + if lane["tests"] != 1 or lane["failures"] != 0 or lane["skips_or_xfails"] != 0: + raise PreflightError("release evidence installed component package lane is not all-pass") + component_report = Path(lane["path"]).resolve() + if not _inside(directory, component_report): + raise PreflightError( + "release evidence installed component package JUnit path escapes its directory") + _artifact_file( + directory, + component_report.relative_to(directory), + lane["sha256"], + label="installed component package JUnit", + ) + component_commands = [ + command for command in python_conformance["commands"] + if INSTALLED_COMPONENT_PACKAGE_NODEID in command["argv"] + ] + if len(component_commands) != 1: + raise PreflightError( + "release evidence must execute the installed component package node exactly once") + component_argv = component_commands[0]["argv"] + include_assignments = [ + argument for argument in component_argv if argument.startswith("POPS_INCLUDE=") + ] + if include_assignments != ["POPS_INCLUDE="] \ + or "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1" not in component_argv: + raise PreflightError( + "installed component package proof must use only wheel-owned headers") + expected_suffix = [ + "python", + "-m", + "pytest", + "-q", + "-s", + INSTALLED_COMPONENT_PACKAGE_NODEID, + "--junitxml", + lane["path"], + ] + if component_argv[-len(expected_suffix):] != expected_suffix: + raise PreflightError("installed component package proof command drifted") + + def _evidence(path: Path, contract: Any, commit: str, runtime: dict[str, str]) -> None: payload = json.loads(path.read_text(encoding="utf-8")) expected = {"schema_version", "producer", "commit_sha", "package_version", "contract_sha256", @@ -503,55 +558,7 @@ def _evidence(path: Path, contract: Any, commit: str, runtime: dict[str, str]) - label="%s JUnit" % name) if gates["python_conformance"]["evidence"]["selection"] != PYTHON_REQUIRED_SELECTION: raise PreflightError("release evidence Python required-lane selection drifted") - component = gates["python_conformance"]["evidence"]["installed_component_package"] - if not isinstance(component, dict) or set(component) != {"nodeid", "headers", "lane"}: - raise PreflightError("release evidence installed component package lane is malformed") - if component["nodeid"] != INSTALLED_COMPONENT_PACKAGE_NODEID \ - or component["headers"] != "installed-wheel": - raise PreflightError("release evidence installed component package authority drifted") - lane = component["lane"] - if not isinstance(lane, dict) or set(lane) != { - "path", "sha256", "tests", "failures", "skips_or_xfails"}: - raise PreflightError("release evidence installed component package JUnit is malformed") - if lane["tests"] != 1 or lane["failures"] != 0 or lane["skips_or_xfails"] != 0: - raise PreflightError("release evidence installed component package lane is not all-pass") - component_report = Path(lane["path"]).resolve() - if not _inside(directory, component_report): - raise PreflightError( - "release evidence installed component package JUnit path escapes its directory") - _artifact_file( - directory, - component_report.relative_to(directory), - lane["sha256"], - label="installed component package JUnit", - ) - component_commands = [ - command for command in gates["python_conformance"]["commands"] - if INSTALLED_COMPONENT_PACKAGE_NODEID in command["argv"] - ] - if len(component_commands) != 1: - raise PreflightError( - "release evidence must execute the installed component package node exactly once") - component_argv = component_commands[0]["argv"] - include_assignments = [ - argument for argument in component_argv if argument.startswith("POPS_INCLUDE=") - ] - if include_assignments != ["POPS_INCLUDE="] \ - or "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1" not in component_argv: - raise PreflightError( - "installed component package proof must use only wheel-owned headers") - expected_suffix = [ - "python", - "-m", - "pytest", - "-q", - "-s", - INSTALLED_COMPONENT_PACKAGE_NODEID, - "--junitxml", - lane["path"], - ] - if component_argv[-len(expected_suffix):] != expected_suffix: - raise PreflightError("installed component package proof command drifted") + _installed_component_package_evidence(directory, gates["python_conformance"]) _examples_evidence(directory, gates, runtime) From 9642bacf8327e4a16bb7d2dd52b22eea6537c54a Mon Sep 17 00:00:00 2001 From: desp0042 Date: Thu, 30 Jul 2026 07:54:57 +0200 Subject: [PATCH 3/5] test(release): lock wheel-owned AOT evidence --- .../architecture/test_final_release_gate.py | 105 ++++++++++++++++++ .../test_external_component_package.py | 26 ++++- 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/tests/python/architecture/test_final_release_gate.py b/tests/python/architecture/test_final_release_gate.py index 4f5909843..513661e48 100644 --- a/tests/python/architecture/test_final_release_gate.py +++ b/tests/python/architecture/test_final_release_gate.py @@ -1,6 +1,7 @@ """Source-only contract checks for the final release gate (ADC-695).""" from __future__ import annotations +import copy import hashlib import importlib.util import json @@ -138,6 +139,110 @@ def test_final_gate_pins_one_conda_environment_and_native_headers( assert "bash" not in command +def test_installed_component_lane_clears_checkout_headers(monkeypatch, tmp_path): + executable = tmp_path / "conda" + executable.write_text("#!/bin/sh\nexit 0\n") + executable.chmod(0o755) + monkeypatch.setenv("POPS_CONDA_EXE", str(executable)) + command = gate._conda_command( + [ + "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1", + "python", + "-m", + "pytest", + contract.INSTALLED_COMPONENT_PACKAGE_NODEID, + ], + pops_include=None, + ) + + assert [ + argument for argument in command if argument.startswith("POPS_INCLUDE=") + ] == ["POPS_INCLUDE="] + assert "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1" in command + assert str((ROOT / "include").resolve()) not in command + + +def test_installed_component_node_is_real_and_rejects_mock_native_routes(): + relative, node = contract.INSTALLED_COMPONENT_PACKAGE_NODEID.split("::", 1) + source = (ROOT / relative).read_text(encoding="utf-8") + assert "def %s(" % node in source + helper = source.split("def _require_installed_component_package_proof()", 1)[1].split( + "\ndef ", 1 + )[0] + assert "Path(_pops.__file__).resolve()" in helper + assert "importlib.machinery.EXTENSION_SUFFIXES" in helper + assert "_pops.__has_kokkos__ is True" in helper + assert '["schema_version"] == 1' in helper + test_body = source.split("def %s(" % node, 1)[1].split("\ndef ", 1)[0] + assert test_body.index("_require_installed_component_package_proof()") \ + < test_body.index("compile_component(component)") + + +def test_preflight_authenticates_exact_installed_component_lane(tmp_path): + report = tmp_path / "reports" / "installed-component-package.xml" + report.parent.mkdir() + report.write_text( + '', + encoding="utf-8", + ) + lane = { + "path": str(report), + "sha256": hashlib.sha256(report.read_bytes()).hexdigest(), + "tests": 1, + "failures": 0, + "skips_or_xfails": 0, + } + argv = [ + "/proof/conda", + "run", + "--no-capture-output", + "-n", + "pops", + "/usr/bin/env", + "PYTHONPATH=", + "PYTHONNOUSERSITE=1", + "POPS_REQUIRE_NATIVE_TESTS=1", + "POPS_INCLUDE=", + "POPS_PROVE_INSTALLED_COMPONENT_PACKAGE=1", + "python", + "-m", + "pytest", + "-q", + "-s", + contract.INSTALLED_COMPONENT_PACKAGE_NODEID, + "--junitxml", + str(report), + ] + row = { + "commands": [{"argv": argv}], + "evidence": { + "installed_component_package": { + "nodeid": contract.INSTALLED_COMPONENT_PACKAGE_NODEID, + "headers": "installed-wheel", + "lane": lane, + }, + }, + } + preflight._installed_component_package_evidence(tmp_path, row) + + source_headers = copy.deepcopy(row) + source_headers["commands"][0]["argv"][ + source_headers["commands"][0]["argv"].index("POPS_INCLUDE=") + ] = "POPS_INCLUDE=/checkout/include" + with pytest.raises(preflight.PreflightError, match="wheel-owned headers"): + preflight._installed_component_package_evidence(tmp_path, source_headers) + + skipped = copy.deepcopy(row) + skipped["evidence"]["installed_component_package"]["lane"]["skips_or_xfails"] = 1 + with pytest.raises(preflight.PreflightError, match="not all-pass"): + preflight._installed_component_package_evidence(tmp_path, skipped) + + duplicate = copy.deepcopy(row) + duplicate["commands"].append(copy.deepcopy(duplicate["commands"][0])) + with pytest.raises(preflight.PreflightError, match="exactly once"): + preflight._installed_component_package_evidence(tmp_path, duplicate) + + def test_final_gate_honours_explicit_conda_executable(monkeypatch, tmp_path): executable = tmp_path / "conda" executable.write_text("#!/bin/sh\nexit 0\n") diff --git a/tests/python/integration/native_loader/test_external_component_package.py b/tests/python/integration/native_loader/test_external_component_package.py index 1e6e79b57..65a94aeff 100644 --- a/tests/python/integration/native_loader/test_external_component_package.py +++ b/tests/python/integration/native_loader/test_external_component_package.py @@ -1,8 +1,10 @@ """Collected native package test: compile, audit, install, load and call the real ABI consumer.""" from __future__ import annotations -import json +import importlib.machinery import importlib.util +import json +import os import subprocess import sys from dataclasses import replace @@ -38,6 +40,27 @@ EXAMPLE = ROOT / "examples/final/EXEMPLE_SPEC_FINALE_ADVECTION_SCALAIRE_COMPLET.py" +def _require_installed_component_package_proof() -> None: + if os.environ.get("POPS_PROVE_INSTALLED_COMPONENT_PACKAGE") != "1": + return + package_root = Path(pops.__file__).resolve().parent + wheel_include = (package_root / "include").resolve() + assert wheel_include.is_dir() + assert (wheel_include / "pops_headers.manifest").is_file() + assert Path(pops_include()).resolve() == wheel_include + + from pops import _pops + + native_path = Path(_pops.__file__).resolve() + assert native_path.parent == package_root + assert any( + native_path.name.endswith(suffix) + for suffix in importlib.machinery.EXTENSION_SUFFIXES + ) + assert _pops.__has_kokkos__ is True + assert _pops.__native_loader_contract__["schema_version"] == 1 + + def _manifest(*, generic: bool = True, device: str = "cpu") -> ComponentManifest: interface = interfaces.NumericalFlux return ComponentManifest( @@ -352,6 +375,7 @@ def _writer_source(manifest: ComponentManifest) -> bytes: def test_source_component_executes_through_generic_native_loader_and_flux_consumer(tmp_path): + _require_installed_component_package_proof() manifest = _manifest() source = _source(manifest) (tmp_path / "average.cpp").write_bytes(source) From 9266ecff76f20adec67a695dc086fd6d81881c7c Mon Sep 17 00:00:00 2001 From: desp0042 Date: Thu, 30 Jul 2026 07:55:51 +0200 Subject: [PATCH 4/5] docs: record installed-wheel AOT proof --- CHANGELOG.md | 4 ++++ docs/design/external-component-packages.md | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 89338adb0..6b8919463 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning ### Changed +- The final release gate now proves an external source component against the exact installed wheel: + its isolated AOT lane clears the checkout-owned `POPS_INCLUDE`, requires the wheel-owned signed + header tree and native Kokkos extension, compiles/installs/loads the component, and retains one + exact no-skip/no-xfail JUnit result whose node ID and command are reauthenticated by preflight. - AMR checkpoint capability reports now distinguish same-rank bit-identical replay from non-bit-identical rank-count rematerialization with Dense persisted histories. The M3 gate executes the persisted two-rank to one-rank restart proof. The explicit `RegridOnRestart()` diff --git a/docs/design/external-component-packages.md b/docs/design/external-component-packages.md index caed1db16..7ddcfc464 100644 --- a/docs/design/external-component-packages.md +++ b/docs/design/external-component-packages.md @@ -88,4 +88,10 @@ artifacts on the declared failure path. Other devices, scalar types and dimensions remain unavailable until a target variant and every interface operation prove them. The wheel ships the exact signed PoPS header tree under -`pops/include`, so AOT compilation does not depend on a source checkout. +`pops/include`, so AOT compilation does not depend on a source checkout. The release gate proves +this independently of the ordinary source conformance lane: it clears `POPS_INCLUDE`, imports the +retained installed wheel with an empty `PYTHONPATH`, requires `pops_include()` to resolve exactly to +that wheel's `pops/include`, and rejects a stub or mocked native route before compiling, installing, +loading and invoking the external numerical-flux component. The one exact pytest node produces an +all-pass JUnit report; release preflight reauthenticates its node ID, command, wheel-header authority +and report digest, and refuses skips, xfails, duplicate execution or a checkout header override. From 9a853c5e420d021a9711a937a7b001af4e946759 Mon Sep 17 00:00:00 2001 From: desp0042 Date: Thu, 30 Jul 2026 07:56:38 +0200 Subject: [PATCH 5/5] release: normalize retained JUnit paths --- scripts/release_preflight.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/release_preflight.py b/scripts/release_preflight.py index c4771bf84..285cc2dae 100644 --- a/scripts/release_preflight.py +++ b/scripts/release_preflight.py @@ -460,7 +460,7 @@ def _installed_component_package_evidence( "release evidence installed component package JUnit path escapes its directory") _artifact_file( directory, - component_report.relative_to(directory), + component_report.relative_to(directory).as_posix(), lane["sha256"], label="installed component package JUnit", ) @@ -554,7 +554,7 @@ def _evidence(path: Path, contract: Any, commit: str, runtime: dict[str, str]) - report = Path(lane["path"]).resolve() if not _inside(directory, report): raise PreflightError("release evidence %s JUnit path escapes its directory" % name) - _artifact_file(directory, report.relative_to(directory), lane["sha256"], + _artifact_file(directory, report.relative_to(directory).as_posix(), lane["sha256"], label="%s JUnit" % name) if gates["python_conformance"]["evidence"]["selection"] != PYTHON_REQUIRED_SELECTION: raise PreflightError("release evidence Python required-lane selection drifted")