[ADC-680] Prove external AOT from the installed wheel

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()`

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.

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",

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,
@@ -437,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).as_posix(),
+        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",
@@ -485,7 +541,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"]
@@ -498,10 +554,11 @@ 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")
+    _installed_component_package_evidence(directory, gates["python_conformance"])
     _examples_evidence(directory, gates, runtime)
 
 

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"])

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(
+        '<testsuite tests="1"><testcase name="installed-component"/></testsuite>',
+        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")

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)