[ADC-695] Integrate final examples and authenticate exact proofs

.github/workflows/ci.yml

@@ -225,12 +225,18 @@ jobs:
               - 'tests/CMakeLists.txt'
               - 'tests/test_manifest.toml'
               - 'scripts/ci_select_tests.py'
+              # The M4 closure is executed inside the installed MPI/VTK lane below. Any edit to
+              # its ledger, runner, source fence, or workflow must therefore require this job on
+              # the PR that changes the proof, never wait for a later nightly run.
+              - 'tests/gates/m4_runtime_io.toml'
+              - 'tests/python/architecture/test_m4_runtime_io_gate.py'
+              - 'scripts/run_m4_gate.py'
+              - '.github/workflows/ci.yml'
               - 'cmake/**'
               - 'CMakeLists.txt'
               - 'CMakePresets.json'
-            # Les changements de workflows/actions CI sont valides par revue + lint YAML local,
-            # et ne compilent pas Kokkos par defaut. Ajouter `ci-kokkos` pour forcer les gates
-            # Serial, ou `ci-full` pour MPI + OpenMP.
+            # Les autres changements de workflows/actions CI sont valides par revue + lint YAML
+            # local. Le workflow CI lui-meme fait exception car il porte la lane M4 executable.
             # full : un push master ne lance la suite COMPLETE (MPI + Kokkos OpenMP) que si un
             # chemin build/backend a bouge. Conservateur a dessein -- couvre tout ce qui peut affecter
             # l'artefact compile OU le chemin DSL/production exerce par le job kokkos-openmp (dsl.py et
@@ -305,7 +311,7 @@ jobs:
   gate-cpp-prewarm:
     name: ubuntu-latest / Kokkos Serial (C++ prewarm ${{ matrix.lane }})
     runs-on: ubuntu-latest
-    timeout-minutes: 22
+    timeout-minutes: 30
     needs: [changes, set-mode]
     if: needs.set-mode.outputs.cpp_required == 'true'
     strategy:
@@ -365,7 +371,12 @@ jobs:
             return "$status"
           }
           lane_parallelism=4
+          lane_watchdog=18m
           case "${{ matrix.lane }}" in
+            system)
+              lane_parallelism=2
+              lane_watchdog=24m
+              ;;
             amr-base|amr-compressible) lane_parallelism=2 ;;
           esac
           export NINJA_STATUS='[%f/%t elapsed=%es active=%r] '
@@ -381,7 +392,7 @@ jobs:
               --contract-file "$RUNNER_TEMP/cpp-prewarm-contract-${{ matrix.lane }}.json"
           )
           test "${#object_targets[@]}" -gt 0
-          run_with_heartbeat "C++ prewarm ${{ matrix.lane }}" 18m \
+          run_with_heartbeat "C++ prewarm ${{ matrix.lane }}" "$lane_watchdog" \
             cmake --build --preset ci-kokkos --parallel "$lane_parallelism" \
               --target "${object_targets[@]}"
           ccache -s
@@ -592,6 +603,17 @@ jobs:
             --verify-contracts "${compile_contracts[@]}"
           read -r -a cpp_targets <<< "${{ steps.test-plan.outputs.cpp_shard_targets }}"
           if [ "${#cpp_targets[@]}" -eq 0 ]; then
+            # Shard 0 owns target-less CTest contracts even when affected-test routing
+            # assigns it no executable target.
+            if [ "${{ matrix.shard }}" -eq 0 ]; then
+              ctest_inventory="$RUNNER_TEMP/ctest-shard-${{ matrix.shard }}.json"
+              standalone_regex_file="$RUNNER_TEMP/ctest-standalone-shard-${{ matrix.shard }}.regex"
+              ctest --preset ci-kokkos -N --show-only=json-v1 > "$ctest_inventory"
+              python3 scripts/ci_select_tests.py verify-cpp-target-labels \
+                --ctest-json "$ctest_inventory" \
+                --targets "${cpp_targets[@]}" \
+                --standalone-regex-file "$standalone_regex_file"
+            fi
             echo "No affected C++ tests selected for shard ${{ matrix.shard }}."
             exit 0
           fi
@@ -715,6 +737,9 @@ jobs:
       - name: M3 AMR and multi-layout gate manifest
         run: python3 scripts/run_m3_gate.py --check-only
 
+      - name: M4 native runtime and scientific I/O gate manifest
+        run: python3 scripts/run_m4_gate.py --check-only
+
       - name: Generated component catalog
         env:
           PYTHONPATH: ${{ github.workspace }}/python
@@ -732,7 +757,7 @@ jobs:
   gate-python-prewarm:
     name: ubuntu-latest / Kokkos Serial (Python prewarm ${{ matrix.lane }})
     runs-on: ubuntu-latest
-    timeout-minutes: 22
+    timeout-minutes: 30
     needs: [changes, set-mode]
     if: needs.set-mode.outputs.python_required == 'true'
     strategy:
@@ -828,15 +853,19 @@ jobs:
               --contract-file "$RUNNER_TEMP/python-prewarm-contract-${{ matrix.lane }}.json"
           )
           test "${#object_targets[@]}" -gt 0
-          # Four simultaneous GCC frontends for the heavy AMR block seams exhaust a 16 GiB hosted
-          # runner. Two semantic, disjoint lanes keep their independently measured critical paths
-          # below the watchdog; each uses two frontends and preserves O3. The lighter System lane
-          # retains all four runner cores.
+          # Four simultaneous GCC frontends now also exhaust the 16 GiB runner on the grown System
+          # seam. Bound that lane to two frontends and give its cold O3 path the same measured
+          # watchdog margin as OpenMP; the four semantic lanes still execute independently.
           lane_parallelism=4
+          lane_watchdog=18m
           case "${{ matrix.lane }}" in
+            system)
+              lane_parallelism=2
+              lane_watchdog=24m
+              ;;
             amr-base|amr-compressible) lane_parallelism=2 ;;
           esac
-          run_with_heartbeat "Python prewarm ${{ matrix.lane }}" 18m \
+          run_with_heartbeat "Python prewarm ${{ matrix.lane }}" "$lane_watchdog" \
             cmake --build --preset ci-kokkos-python --parallel "$lane_parallelism" \
               --target "${object_targets[@]}"
           ccache -s
@@ -1438,8 +1467,8 @@ jobs:
     name: ubuntu-24.04 / MPI + Kokkos Serial (C++ prewarm ${{ matrix.lane }})
     runs-on: ubuntu-24.04
     # setup-kokkos can consume ~15 minutes on a cold runner. Keep enough room
-    # for the explicit 18-minute compile watchdog and artifact publication.
-    timeout-minutes: 40
+    # for the System lane's explicit 24-minute compile watchdog and artifact publication.
+    timeout-minutes: 50
     needs: [set-mode, changes]
     if: needs.set-mode.outputs.mpi_required == 'true'
     strategy:
@@ -1508,7 +1537,12 @@ jobs:
             return "$status"
           }
           lane_parallelism=4
+          lane_watchdog=18m
           case "${{ matrix.lane }}" in
+            system)
+              lane_parallelism=2
+              lane_watchdog=24m
+              ;;
             amr-base|amr-compressible) lane_parallelism=2 ;;
           esac
           mpi_cmake_args=()
@@ -1531,7 +1565,7 @@ jobs:
               --contract-file "$RUNNER_TEMP/mpi-prewarm-contract-${{ matrix.lane }}.json"
           )
           test "${#object_targets[@]}" -gt 0
-          run_with_heartbeat "MPI prewarm ${{ matrix.lane }}" 18m \
+          run_with_heartbeat "MPI prewarm ${{ matrix.lane }}" "$lane_watchdog" \
             cmake --build --preset ci-mpi --parallel "$lane_parallelism" \
               --target "${object_targets[@]}"
           ccache -s
@@ -1595,7 +1629,7 @@ jobs:
     # The native build, processor-grouped CTest plan, and Python MPI contract
     # fence run sequentially. Each C++ launch retains its configured bounded
     # TIMEOUT; grouping removes PROCESSORS head-of-line blocking without skips.
-    timeout-minutes: 70
+    timeout-minutes: 180
     needs: [set-mode, changes, gate-mpi-prewarm]
     # Suite complete, ou PR qui modifie directement le chemin distribue/MPI.
     if: needs.set-mode.outputs.mpi_required == 'true'
@@ -1632,7 +1666,7 @@ jobs:
           sudo apt-get install -y --no-install-recommends \
             ccache libeigen3-dev libhdf5-openmpi-dev libopenmpi-dev ninja-build openmpi-bin \
             pybind11-dev python3-dev python3-h5py \
-            python3-numpy python3-pytest
+            python3-numpy python3-pytest python3-vtk9
 
       - name: Resolve runner and compiler cache identity
         id: kokkos-platform
@@ -1717,7 +1751,7 @@ jobs:
           test -s build-mpi/mpi-ctest-groups.tsv
 
       - name: Configure + build (MPI + Kokkos Serial)
-        timeout-minutes: 22
+        timeout-minutes: 35
         # Flags : preset ci-mpi (source unique, cf. CMakePresets.json) ; Kokkos_ROOT vient de
         # $KOKKOS_PREFIX (env du job, install en cache). ccache auto-detecte.
         run: |
@@ -1772,6 +1806,10 @@ jobs:
             --build-dir build-mpi \
             --verify-contracts "${compile_contracts[@]}"
           read -r -a mpi_targets <<< "${{ steps.mpi-test-plan.outputs.cpp_label_targets }}"
+          mapfile -t m4_targets < <(
+            /usr/bin/python3 scripts/run_m4_gate.py --list-ctest-targets
+          )
+          test "${#m4_targets[@]}" -gt 0
           export NINJA_STATUS='[%f/%t elapsed=%es active=%r] '
           # The monolithic Python module link is memory-heavy. Keep it isolated
           # from test compilation/linking so a small hosted runner cannot evict
@@ -1780,6 +1818,8 @@ jobs:
             cmake --build --preset ci-mpi --parallel 1 --target _pops
           run_with_heartbeat "MPI native test build" 8m \
             cmake --build --preset ci-mpi --parallel 4 --target "${mpi_targets[@]}"
+          run_with_heartbeat "M4 native test build" 10m \
+            cmake --build --preset ci-mpi --parallel 4 --target "${m4_targets[@]}"
 
       - name: Installed package smoke (MPI-only + collective HDF5)
         run: |
@@ -1935,6 +1975,41 @@ jobs:
             timeout --signal=TERM --kill-after=30s 25m \
               /usr/bin/python3 -m pytest -q -ra --maxfail=1 "$mpi_orchestrator"
           done < build-mpi/python-mpi-orchestrators.txt
+
+      - name: M4 complete native runtime and scientific I/O gate
+        timeout-minutes: 45
+        env:
+          PYTHONPATH: ${{ github.workspace }}/build-mpi/python-package:${{ github.workspace }}
+          POPS_INCLUDE: ${{ github.workspace }}/include
+          POPS_KOKKOS_ROOT: ${{ github.workspace }}/.kokkos-install
+          Kokkos_ROOT: ${{ github.workspace }}/.kokkos-install
+          POPS_CACHE_DIR: ${{ github.workspace }}/.pops-ci/m4-dsl-cache
+          POPS_KEEP_GENERATED: "1"
+          POPS_REQUIRE_MPI_TESTS: "1"
+          POPS_REQUIRE_NATIVE_TESTS: "1"
+          # Ubuntu 24.04 OpenMPI 4 OMPIO selects sharedfp/lockedfile during
+          # HDF5 MPI_File_open and aborts inside its fortified sprintf path.
+          # ROMIO is the packaged OpenMPI MPI-IO component and exercises the
+          # same collective HDF5 contract without that implementation defect.
+          OMPI_MCA_io: "^ompio"
+        run: |
+          # These readers are mandatory capabilities of this lane. Imports happen before the gate
+          # so a missing apt module cannot masquerade as a scientific skip.
+          /usr/bin/python3 - <<'PY'
+          import h5py
+          import numpy
+          from vtkmodules.vtkIOXML import (
+              vtkXMLPUnstructuredGridReader,
+              vtkXMLUnstructuredGridReader,
+          )
+
+          print("M4 readers:", numpy.__version__, h5py.__version__)
+          print(vtkXMLPUnstructuredGridReader, vtkXMLUnstructuredGridReader)
+          PY
+          /usr/bin/python3 scripts/run_m4_gate.py \
+            --build-dir build-mpi \
+            --mpi-exec mpiexec
+
       - name: ccache stats (MPI)
         if: always()
         run: ccache -s

.github/workflows/quality.yml

@@ -142,27 +142,31 @@ jobs:
           else
             echo "racine propre (aucun artefact a la racine)"
           fi
-      - name: Couverture manifest de tests (test_manifest.toml, informatif)
+      - name: Couverture manifest de tests (test_manifest.toml, bloquante)
         if: always()
         run: |
           # gen_test_counts.py --check-matrix liste les tests disque absents de tests/test_manifest.toml.
-          # Non bloquant (set +e) : informatif jusqu'a ce que le manifest soit complet, puis bloquant.
+          # Le manifest est complet : toute nouvelle entree disque non declaree est une regression.
+          # Capturer le statut permet de publier le detail avant d'echouer explicitement.
           set +e
           out=$(python3 docs/gen_test_counts.py --check-matrix)
           rc=$?
           set -e
           echo "$out"
           n=$(printf '%s\n' "$out" | grep -c '^MISSING' || true)   # grep -c exit 1 si 0 match -> || true (sinon set -e tue l'etape quand la matrice est complete)
           if [ "$rc" -ne 0 ]; then
-            echo "::warning::tests/test_manifest.toml : $n test(s) sans entree (anti-derive)"
+            echo "::error::tests/test_manifest.toml : $n test(s) sans entree (anti-derive)"
           fi
           {
             echo "### Couverture manifest de tests"
             echo ""
             echo "- Tests absents de \`tests/test_manifest.toml\` : **$n**"
             echo ""
-            echo "_Informatif : ajouter l'entree du test dans le manifest ; bloquant une fois complet._"
+            echo "_Bloquant : tout test doit appartenir au manifest autoritatif._"
           } >> "$GITHUB_STEP_SUMMARY"
+          if [ "$rc" -ne 0 ]; then
+            exit "$rc"
+          fi
 
   # --- Prewarm natif : contrats exacts par profil qualite ----------------------------------------
   # Warnings, ASan et coverage portent trois jeux de flags incompatibles avec le build de production

.github/workflows/release.yml

@@ -35,7 +35,10 @@ jobs:
     name: Validate the exact published wheel
     needs: wheel
     runs-on: macos-14
-    timeout-minutes: 40
+    # The complete source suite is already the parallel ``full-source-matrix`` dependency. This
+    # wheel lane runs the bounded M4/final-example ledger once, then CTest and artifact/restart
+    # proofs against the exact retained wheel. Keep enough room for an uncached native build.
+    timeout-minutes: 180
     steps:
       - uses: actions/checkout@v7
         with:
@@ -61,15 +64,21 @@ jobs:
           wheels=("$RUNNER_TEMP"/wheelhouse/pops-*.whl)
           test "${#wheels[@]}" -eq 1
           evidence="$RUNNER_TEMP/pops-final-evidence.json"
+          public_api_evidence="$RUNNER_TEMP/pops-final-evidence-public-api.json"
           python scripts/run_final_gate.py --wheel "${wheels[0]}" --evidence "$evidence"
+          python scripts/prove_public_api_parity.py \
+            --wheel "${wheels[0]}" \
+            --installed \
+            --evidence "$public_api_evidence"
           python - <<'PY'
           from pops.runtime_environment import runtime_environment_report
           report = runtime_environment_report()
           assert report["kokkos_backend"] == "Serial", report
           assert report["mpi_compiled"] is False, report
           PY
           python scripts/release_preflight.py \
-            --release --tag "$GITHUB_REF_NAME" --installed --evidence "$evidence"
+            --release --tag "$GITHUB_REF_NAME" --installed --evidence "$evidence" \
+            --public-api-evidence "$public_api_evidence"
 
       - name: Retain authenticated release evidence
         uses: actions/upload-artifact@v7