Alpha 4 Release

.github/workflows/benchmark_dispatch.yml

@@ -0,0 +1,122 @@
+# Tell openswmm.engine.benchmarks that this engine moved, so it can build THIS
+# commit and sweep the model corpus against it.
+#
+# Why a dispatch rather than a job here: the benchmark platform owns the corpus,
+# the engine registry, the scoring taxonomy and its own Pages site. Keeping the
+# sweep there means this repository needs only permission to say "a new commit
+# exists" -- it never needs a Pages credential, and the corpus never has to be
+# vendored into this tree.
+#
+# Gated on Unit Testing succeeding. A sweep is a multi-hour, multi-runner job;
+# dispatching a commit that does not build wastes it and buries the real signal
+# under a matrix of ERROR cells.
+name: Benchmark dispatch
+
+on:
+  workflow_run:
+    workflows: ["Unit Testing"]
+    types: [completed]
+    branches: [main, develop]
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Engine commit to benchmark (blank = this branch's HEAD)
+        required: false
+
+permissions:
+  contents: read
+
+env:
+  BENCHMARKS_REPO: HydroCouple/openswmm.engine.benchmarks
+
+jobs:
+  dispatch:
+    name: Notify the benchmark platform
+    # workflow_run fires on completion regardless of outcome, so filter to the
+    # successful PUSH runs. Pull-request runs are excluded deliberately: a fork
+    # PR cannot read secrets, and a sweep per PR would cost more than it tells
+    # us until the PR tier is curated.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve the commit to benchmark
+        id: target
+        env:
+          RUN_SHA: ${{ github.event.workflow_run.head_sha }}
+          RUN_REF: ${{ github.event.workflow_run.head_branch }}
+          INPUT_SHA: ${{ inputs.sha }}
+        run: |
+          set -euo pipefail
+          sha="${INPUT_SHA:-${RUN_SHA:-${GITHUB_SHA}}}"
+          ref="${RUN_REF:-${GITHUB_REF_NAME}}"
+          # A blank sha would make the receiver silently check out its default
+          # branch and publish results keyed to the wrong commit.
+          if [ -z "$sha" ]; then
+            echo "::error::could not resolve an engine SHA to dispatch"
+            exit 1
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+          echo "Dispatching $ref @ $sha to $BENCHMARKS_REPO"
+
+      - name: Check the dispatch token is configured
+        env:
+          TOKEN: ${{ secrets.BENCHMARKS_DISPATCH_TOKEN }}
+        run: |
+          if [ -n "${TOKEN:-}" ]; then exit 0; fi
+          cat >&2 <<'MSG'
+          The secret BENCHMARKS_DISPATCH_TOKEN is not set on this repository.
+
+          Cross-repository repository_dispatch cannot use the default
+          GITHUB_TOKEN -- it is scoped to this repository only -- so a separate
+          credential is required.
+
+          To configure:
+            1. Create a token that may POST to
+               HydroCouple/openswmm.engine.benchmarks:
+                 * fine-grained PAT  -> Repository access: that repo,
+                                        Permissions: Contents = Read and write
+                 * classic PAT       -> scope: repo
+               (A GitHub App installation token works too, and is preferable
+                for a shared org: it is not tied to one person's account.)
+            2. Add it here as an Actions secret named
+               BENCHMARKS_DISPATCH_TOKEN.
+
+          Until then the benchmark platform picks this engine up only via its
+          own nightly cron (07:00 UTC, building `develop`), not per push.
+          MSG
+          echo "::error::BENCHMARKS_DISPATCH_TOKEN is not configured -- see the log above"
+          exit 1
+
+      - name: Dispatch to openswmm.engine.benchmarks
+        env:
+          TOKEN: ${{ secrets.BENCHMARKS_DISPATCH_TOKEN }}
+          SHA: ${{ steps.target.outputs.sha }}
+          REF: ${{ steps.target.outputs.ref }}
+        run: |
+          set -euo pipefail
+          # Built with jq, not string interpolation: a branch name is
+          # attacker-influenced text and must not be able to break out of the
+          # JSON body.
+          payload=$(jq -n \
+            --arg sha "$SHA" \
+            --arg ref "$REF" \
+            --arg repo "$GITHUB_REPOSITORY" \
+            --arg run_url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/${{ github.event.workflow_run.id || github.run_id }}" \
+            '{event_type: "engine-push",
+              client_payload: {sha: $sha, ref: $ref, repo: $repo, run_url: $run_url}}')
+
+          curl --fail-with-body -sS -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            "$GITHUB_API_URL/repos/$BENCHMARKS_REPO/dispatches" \
+            -d "$payload"
+
+          echo "Dispatched $REF @ $SHA"
+          echo "### Benchmark sweep dispatched" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "\`$REF\` @ \`$SHA\` -> [$BENCHMARKS_REPO]($GITHUB_SERVER_URL/$BENCHMARKS_REPO/actions)" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/codeql.yml

@@ -1,5 +1,8 @@
 name: CodeQL
 
+permissions:
+  contents: read
+
 on:
   push:
     branches: [main]                         # drop develop — covered by PR
@@ -52,7 +55,7 @@ jobs:
         uses: actions/checkout@v5
         with:
           repository: microsoft/vcpkg
-          ref: 2025.02.14
+          ref: 2026.07.29
           path: vcpkg
 
       - name: Install Ninja

.github/workflows/deployment.yml

@@ -1,5 +1,8 @@
 name: Deployment
 
+permissions:
+  contents: read
+
 on:
   push:
     branches: [main]
@@ -14,7 +17,7 @@ env:
   OMP_NUM_THREADS: 1
   # Single source of truth for the vcpkg ref (used by every checkout + the
   # in-container clone in pyproject's linux before-all via environment-pass).
-  VCPKG_REF: "2025.02.14"
+  VCPKG_REF: "2026.07.29"
   # macOS minimum target. Set globally so the engine build job AND vcpkg's
   # dependency builds (SUNDIALS/HDF5/sqlite3) compile at this floor; ignored on
   # Linux/Windows. The Python wheels set the same value via cibuildwheel
@@ -23,14 +26,16 @@ env:
   MACOSX_DEPLOYMENT_TARGET: "11.0"
 
 jobs:
+  python-contracts:
+    uses: ./.github/workflows/python_contracts.yml
+
   # ──────────────────────────────────────────────────────────────────────
   #  Build release binaries
   # ──────────────────────────────────────────────────────────────────────
   build:
     name: "Build (${{ matrix.alias }})"
     permissions:
       contents: read
-      actions: write   # x-gha vcpkg binary cache + actions/cache
     strategy:
       fail-fast: false
       matrix:
@@ -131,6 +136,15 @@ jobs:
         with:
           arch: amd64
 
+      - name: Re-pin VCPKG_ROOT (Windows)
+        # vcvars64 (VS 2022 17.6+) exports VCPKG_ROOT pointing at Visual
+        # Studio's bundled vcpkg, and msvc-dev-cmd forwards it to every later
+        # step, overriding the job-level env — so configure would silently
+        # build against VS's port snapshot instead of the pinned checkout.
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: echo "VCPKG_ROOT=${{ github.workspace }}\vcpkg" >> $env:GITHUB_ENV
+
       - name: Configure (Release)
         # Release packaging skips the test/benchmark targets so vcpkg pulls only
         # the runtime deps. Kokkos + hypre/AMG are vcpkg/CMake defaults, but
@@ -215,7 +229,6 @@ jobs:
     # not block all wheels. (Previously `needs: build` coupled them.)
     permissions:
       contents: read
-      actions: write
     strategy:
       fail-fast: false
       matrix:
@@ -299,7 +312,6 @@ jobs:
     name: "GPU-omp wheels (${{ matrix.os }})"
     permissions:
       contents: read
-      actions: write
     strategy:
       fail-fast: false
       matrix:
@@ -426,17 +438,22 @@ jobs:
           # numpy (the base wheel's only runtime dep) is pulled from PyPI as a wheel.
           "$PY" -m pip install --only-binary :all: numpy
           # The project wheels MUST come from the local wheelhouse, never PyPI.
-          # openswmm / openswmm-gpu-omp are pre-releases (6.0.0a3), and a *stable*
+          # openswmm / openswmm-gpu-omp are pre-releases (for example, 6.0.0a4.dev1), and a *stable*
           # openswmm-gpu-omp 0.0.0 placeholder exists on PyPI; without --no-index pip
           # prefers that stable stub over our local pre-release and installs an empty
           # package (ModuleNotFoundError: openswmm_gpu_omp). --no-index also makes a
           # missing or mis-tagged companion wheel fail loudly here instead of silently
           # resolving to PyPI.
           "$PY" -m pip install --only-binary :all: --no-index --find-links wheelhouse openswmm openswmm-gpu-omp
           "$PY" -m pip show openswmm | tee wheel-smoke-${{ matrix.os }}.txt
-          # gpu-omp companion must import AND be auto-discovered by base openswmm
-          # (import openswmm runs _register_gpu_companion → OPENSWMM_GPU_PLUGIN_PATH).
-          "$PY" -c "import os,openswmm,openswmm_gpu_omp as g; p=os.environ.get('OPENSWMM_GPU_PLUGIN_PATH'); assert p, 'gpu-omp plugin not discovered'; print('OPENSWMM_GPU_PLUGIN_PATH='+p); print('companion at '+g.__file__)" | tee -a wheel-smoke-${{ matrix.os }}.txt
+          # A plugin must be auto-discovered on `import openswmm`
+          # (_register_gpu_plugin → OPENSWMM_GPU_PLUGIN_PATH), the companion must
+          # import, and the discovered directory must actually CONTAIN a built
+          # plugin binary — a non-empty env var alone would pass even if the
+          # OpenMP build had silently produced nothing. The base wheel now ships
+          # the plugin too, so the discovered dir is normally openswmm/engine;
+          # the shim prefers it and skips the companion (one OpenMP runtime).
+          "$PY" -c "import os,glob,openswmm,openswmm_gpu_omp as g; p=os.environ.get('OPENSWMM_GPU_PLUGIN_PATH'); assert p, 'no gpu plugin discovered'; d=p.split(os.pathsep)[0]; hits=[f for f in glob.glob(os.path.join(d,'*openswmm_gpu_*')) if f.endswith(('.so','.dylib','.dll'))]; assert hits, 'discovered dir has no plugin binary: '+d; print('OPENSWMM_GPU_PLUGIN_PATH='+p); print('plugin: '+hits[0]); print('companion at '+g.__file__)" | tee -a wheel-smoke-${{ matrix.os }}.txt
           # Run the example model end-to-end via the shared smoke script.
           "$PY" python/smoke_test.py 2>&1 | tee -a wheel-smoke-${{ matrix.os }}.txt
 
@@ -463,7 +480,9 @@ jobs:
           python-version: "3.13"
 
       - name: Check version sync (CMake / vcpkg / pyproject)
-        run: python scripts/check_version_sync.py
+        run: |
+          python -m unittest discover -s scripts -p test_version_sync.py
+          python scripts/check_version_sync.py
 
       - name: Install build frontend
         run: |
@@ -494,7 +513,6 @@ jobs:
     name: "C++ unit tests (release gate)"
     permissions:
       contents: read
-      actions: write
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -544,7 +562,7 @@ jobs:
   release:
     name: Create GitHub Release
     if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build, test, wheels, gpu-omp-wheels, sdist, wheel-smoke]
+    needs: [build, test, wheels, gpu-omp-wheels, sdist, wheel-smoke, python-contracts]
     runs-on: ubuntu-latest
     permissions:
       contents: write