BNG3: integrate native backend and parity safeguards

.github/workflows/ci.yml

@@ -7,8 +7,10 @@ on:
     branches: [main]
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  # Keep hosted evidence attached to the exact PR head being evaluated. A
+  # checklist/documentation push must not cancel the preceding semantic run.
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: false
 
 env:
   CMAKE_BUILD_TYPE: Release
@@ -31,7 +33,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install linters and policy dependencies
-        run: pip install black ruff pytest
+        run: pip install black ruff pytest numpy
 
       - name: Check Python formatting (Black)
         run: black --check --diff --target-version py312 python/ tests/python/ scripts/
@@ -64,6 +66,9 @@ jobs:
       - name: Enforce validation exception budget
         run: python -m tests.validation.exception_ledger --max-exceptions 1
 
+      - name: Run CI contract tests
+        run: python -m pytest tests/test_ci_contract.py -q
+
   # ═══════════════════════════════════════════════════════════════════════════
   # C++ Build & Test (BNG engine with embedded NFsim library)
   # ═══════════════════════════════════════════════════════════════════════════
@@ -188,7 +193,7 @@ jobs:
   # ═══════════════════════════════════════════════════════════════════════════
 
   validation:
-    name: Validation (${{ matrix.os }})
+    name: Validation (supported reference subset, ${{ matrix.os }})
     needs: cpp-build
     runs-on: ${{ matrix.os }}
     strategy:
@@ -222,12 +227,13 @@ jobs:
         if: "!startsWith(matrix.os, 'windows')"
         run: chmod +x build/cpp/bng_cpp*
 
-      - name: Run validation against reference .net files
+      - name: Run supported validation against reference .net files
         shell: bash
         run: |
           BNG=build/cpp/bng_cpp${{ startsWith(matrix.os, 'windows') && '.exe' || '' }}
-          SKIP="--skip michment_cont,test_sbml_flat,test_sbml_structured,Repressilator,SHP2_base_model"
-          python scripts/validate.py --bng-cpp "$BNG" $SKIP --verbose
+          python scripts/validate.py --bng-cpp "$BNG" --strict-references \
+            --skip-file tests/validation/reference_exclusions.json \
+            --skip-profile pull_request --verbose
 
   # ═══════════════════════════════════════════════════════════════════════════
   # BNGL corpus parse inventory (not an NFsim simulation check)
@@ -297,7 +303,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-22.04, macos-14, windows-2022]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4
@@ -319,7 +325,7 @@ jobs:
         uses: ilammy/msvc-dev-cmd@v1
 
       - name: Install Python build dependencies
-        run: pip install scikit-build-core pybind11 numpy pytest pytest-cov cement colorlog pyparsing pylru pandas matplotlib python-libsbml pyyaml lxml networkx sympy seaborn xmltodict
+        run: pip install scikit-build-core pybind11 numpy click pytest pytest-cov cement colorlog pyparsing pylru pandas matplotlib python-libsbml pyyaml lxml networkx sympy seaborn xmltodict
 
       - name: Build and install package (Windows)
         if: startsWith(matrix.os, 'windows')
@@ -336,10 +342,26 @@ jobs:
         env:
           CMAKE_ARGS: "-DBUILD_TESTS=OFF -DBUILD_CLI=OFF"
 
+      - name: Seed isolated Matplotlib font cache (Unix)
+        if: matrix.os == 'ubuntu-22.04' && (matrix.python-version == '3.9' || matrix.python-version == '3.10')
+        run: python scripts/prepare_matplotlib_cache.py
+        env:
+          MPLBACKEND: Agg
+          MPLCONFIGDIR: ${{ runner.temp }}/matplotlib
+
       - name: Run Python tests
-        run: pytest tests/python/ -v --tb=short --cov=bionetgen --cov-report=xml
+        run: pytest tests/python/test_sbml_import.py -v --tb=short
         env:
           SYMPY_USE_GMPY: "0"
+          MPLBACKEND: Agg
+          MPLCONFIGDIR: ${{ runner.temp }}/matplotlib
+
+      - name: Run Python tests
+        run: pytest tests/python/ -v --tb=short --cov=bionetgen --cov-report=xml --ignore=tests/python/test_sbml_import.py
+        env:
+          SYMPY_USE_GMPY: "0"
+          MPLBACKEND: Agg
+          MPLCONFIGDIR: ${{ runner.temp }}/matplotlib
 
       - name: Upload coverage
         if: matrix.os == 'ubuntu-22.04' && matrix.python-version == '3.12'
@@ -406,6 +428,50 @@ jobs:
         env:
           SYMPY_USE_GMPY: "0"
 
+  # ═══════════════════════════════════════════════════════════════════════════
+  # Source Distribution Installation Smoke Test
+  # ═══════════════════════════════════════════════════════════════════════════
+
+  package-smoke:
+    name: Package Smoke (sdist)
+    needs: [python-test]
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install packaging and native build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake ninja-build
+          python -m pip install build
+
+      - name: Build source distribution
+        run: python -m build --sdist
+
+      - name: Install source distribution in clean environment
+        shell: bash
+        run: |
+          set -eu
+          python -m venv "$RUNNER_TEMP/bng3-package-smoke"
+          "$RUNNER_TEMP/bng3-package-smoke/bin/python" -m pip install --upgrade pip
+          "$RUNNER_TEMP/bng3-package-smoke/bin/python" -m pip install numpy click
+          "$RUNNER_TEMP/bng3-package-smoke/bin/python" -m pip install --no-deps dist/*.tar.gz
+        env:
+          CMAKE_ARGS: "-DBUILD_TESTS=OFF -DBUILD_CLI=OFF"
+
+      - name: Smoke installed package
+        shell: bash
+        run: |
+          set -eu
+          "$RUNNER_TEMP/bng3-package-smoke/bin/python" -c \
+            "import bionetgen; import bionetgen._bionetgen_cpp"
+          "$RUNNER_TEMP/bng3-package-smoke/bin/bionetgen" --version
+          "$RUNNER_TEMP/bng3-package-smoke/bin/bionetgen" --help
+
   # ═══════════════════════════════════════════════════════════════════════════
   # Wheel Building (binary distribution)
   # ═══════════════════════════════════════════════════════════════════════════
@@ -437,10 +503,10 @@ jobs:
       - name: Build wheels
         run: cibuildwheel --output-dir wheelhouse
         env:
-          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*"
           CIBW_SKIP: "*-musllinux_* *-manylinux_i686 *-win32"
           CIBW_BUILD_VERBOSITY: 1
-          CIBW_TEST_REQUIRES: pytest numpy
+          CIBW_TEST_REQUIRES: pytest numpy click
           CIBW_TEST_COMMAND: pytest {project}/tests/python/test_cpp_backend.py -v --tb=short
           CIBW_ENVIRONMENT: CMAKE_ARGS="-DBUILD_TESTS=OFF -DBUILD_CLI=OFF"
           # macOS: build universal2 wheels

.github/workflows/codeql.yml

@@ -0,0 +1,64 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: cpp
+            build-mode: manual
+          - language: python
+            build-mode: none
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Install C++ build dependencies
+        if: matrix.language == 'cpp'
+        run: sudo apt-get update && sudo apt-get install -y cmake ninja-build
+
+      - name: Configure C++ project
+        if: matrix.language == 'cpp'
+        run: >-
+          cmake -B build -G Ninja
+          -DCMAKE_BUILD_TYPE=Release
+          -DBUILD_PYTHON_BINDINGS=OFF
+          -DBUILD_CLI=OFF
+          -DBUILD_NFSIM_CLI=OFF
+          -DBUILD_TESTS=OFF
+
+      - name: Build C++ project
+        if: matrix.language == 'cpp'
+        run: cmake --build build --parallel 2
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/release.yml

@@ -107,9 +107,9 @@ jobs:
       - name: Build wheels
         run: cibuildwheel --output-dir wheelhouse
         env:
-          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*"
           CIBW_SKIP: "*-musllinux_* *-manylinux_i686 *-win32"
-          CIBW_TEST_REQUIRES: pytest numpy
+          CIBW_TEST_REQUIRES: pytest numpy click
           CIBW_TEST_COMMAND: pytest {project}/tests/python/test_cpp_backend.py -v --tb=short
           CIBW_ENVIRONMENT: CMAKE_ARGS="-DBUILD_TESTS=OFF -DBUILD_CLI=OFF"
           CIBW_ARCHS_MACOS: "arm64 x86_64"

.github/workflows/weekly.yml

@@ -10,11 +10,11 @@ env:
 
 jobs:
   # ═══════════════════════════════════════════════════════════════════════════
-  # Full BNG Network Generation Validation
+  # Supported BNG Network Generation Validation
   # ═══════════════════════════════════════════════════════════════════════════
 
   bng-validation:
-    name: BNG Validation (${{ matrix.os }})
+    name: BNG Validation (supported reference subset, ${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -50,16 +50,17 @@ jobs:
             -DBUILD_TESTS=OFF
           cmake --build build --config Release
 
-      - name: Run full validation
+      - name: Run supported validation
         shell: bash
         run: |
-          SKIP="--skip michment_cont,test_sbml_flat,test_sbml_structured,Repressilator,SHP2_base_model,Motivating_example_cBNGL,blbr"
           if [[ "${{ matrix.os }}" == *windows* ]]; then
             BNG=build/cpp/bng_cpp.exe
           else
             BNG=build/cpp/bng_cpp
           fi
-          python scripts/validate.py --bng-cpp "$BNG" $SKIP --verbose
+          python scripts/validate.py --bng-cpp "$BNG" --strict-references \
+            --skip-file tests/validation/reference_exclusions.json \
+            --skip-profile weekly --verbose
 
   # ═══════════════════════════════════════════════════════════════════════════
   # NFsim execution smoke test (not a statistical parity check)
@@ -211,7 +212,7 @@ jobs:
 
       - name: Run cross-validation
         run: |
-          set -e
+          set -euo pipefail
           BNG_CPP=build/cpp/bng_cpp
           BNG_PERL=legacy/perl/BNG2.pl
           MODELS_DIR=tests/validation/Validate
@@ -223,16 +224,18 @@ jobs:
 
           PASS=0
           FAIL=0
-          SKIP=0
+          TOTAL=0
 
           for bngl in "$MODELS_DIR"/*.bngl; do
             model=$(basename "$bngl" .bngl)
+            TOTAL=$((TOTAL + 1))
             tmpdir=$(mktemp -d)
 
             # Run C++ engine
             cp "$bngl" "$tmpdir/"
             if ! timeout 30 "$BNG_CPP" "$tmpdir/$model.bngl" > /dev/null 2>&1; then
-              SKIP=$((SKIP + 1))
+              echo "FAIL $model: C++ execution failed"
+              FAIL=$((FAIL + 1))
               rm -rf "$tmpdir"
               continue
             fi
@@ -242,7 +245,8 @@ jobs:
             perl_tmpdir=$(mktemp -d)
             cp "$bngl" "$perl_tmpdir/"
             if ! timeout 60 perl "$BNG_PERL" "$perl_tmpdir/$model.bngl" > /dev/null 2>&1; then
-              SKIP=$((SKIP + 1))
+              echo "FAIL $model: Perl execution failed"
+              FAIL=$((FAIL + 1))
               rm -rf "$tmpdir" "$perl_tmpdir"
               continue
             fi
@@ -260,7 +264,8 @@ jobs:
                 FAIL=$((FAIL + 1))
               fi
             else
-              SKIP=$((SKIP + 1))
+              echo "FAIL $model: one or both .net outputs are missing"
+              FAIL=$((FAIL + 1))
             fi
 
             rm -rf "$tmpdir" "$perl_tmpdir"
@@ -269,11 +274,11 @@ jobs:
           {
             echo "### C++ vs Perl Cross-Validation"
             echo ""
-            echo "| Passed | Failed | Skipped |"
+            echo "| Total | Passed | Failed |"
             echo "| ---: | ---: | ---: |"
-            echo "| $PASS | $FAIL | $SKIP |"
+            echo "| $TOTAL | $PASS | $FAIL |"
           } | tee -a "$GITHUB_STEP_SUMMARY"
 
-          if [ "$PASS" -eq 0 ] || [ "$FAIL" -gt 0 ]; then
+          if [ "$TOTAL" -eq 0 ] || [ "$FAIL" -gt 0 ]; then
             exit 1
           fi