Tests and Benchmarks for regression

.github/workflows/contract-tests.yml

@@ -0,0 +1,58 @@
+name: Contract suite — functional (blocking)
+
+# PRD user story 23 (issue #1): the whole suite runs in CI on every PR so a
+# change breaking any pinned capability fails fast. This is the BLOCKING
+# functional leg — a plain (non-sanitized) build that runs everything ctest
+# knows about, including the Death tests and the CurrentlyCorrupts tripwires
+# that the informational sanitizer leg (sanitizers.yml) excludes. An xfail
+# flipping to pass (a DISABLED_ test's tripwire going red) or a green test
+# going red both fail this check.
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+
+jobs:
+  contract-functional:
+    name: Contract tests (Linux, ${{ matrix.preset }}, blocking)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both build modes (issue #32): the dlopen-failure plugin pin is
+        # build-mode dependent — assert-abort death test in Debug, swallowed
+        # assert tripwire under NDEBUG (RelWithDebInfo) — so each branch needs
+        # its own leg or one of them never runs anywhere. The presets
+        # (CMakePresets.json) are the single source of truth for flags and
+        # binary dirs; builddir here only feeds the label-partition check.
+        include:
+          - preset: tests        # RelWithDebInfo
+            builddir: build
+          - preset: tests-debug
+            builddir: build-debug
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # git describe needs full history for the version macro
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build libhdf5-dev libboost-filesystem-dev
+
+      - name: Configure (tests on, no Python bindings)
+        run: cmake --preset ${{ matrix.preset }}
+
+      - name: Build
+        run: cmake --build --preset ${{ matrix.preset }}
+
+      # Issue #31: an empty `ctest -L unit` exits 0, so a broken label
+      # partition is invisible to the test run below — check it explicitly.
+      - name: Verify unit/integration label partition
+        run: bash tests/contract/check_label_partition.sh ${{ matrix.builddir }}/tests/contract
+
+      - name: Run the whole test suite
+        run: ctest --preset ${{ matrix.preset }}

.github/workflows/docs.yml

@@ -52,7 +52,7 @@ jobs:
           else
             VERSION=dev
           fi
-          echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
+          echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Build documentation
         env:

.github/workflows/mdsplus-contract.yml

@@ -0,0 +1,124 @@
+name: MDSplus contract suite (non-blocking)
+
+# Task 2 issue #18 (parent #12): a dedicated, informational CI leg for the
+# MDSplus tier (tests/contract/test_mdsplus*.cpp, TRACEABILITY.md Part 4),
+# mirroring the D7 sanitizer leg (sanitizers.yml). continue-on-error: true —
+# informational, not a merge gate, until the characterization baseline
+# (issues #13-17) is triaged. Promotion to a blocking gate is deferred to
+# Task 3.
+#
+# Runs on a GitHub-hosted arm64 runner: MDSplus publishes no arm64 packages
+# for Ubuntu 22, only 24.04+ (docker/mdsplus/README.md's deviation note), and
+# the characterization image itself is aarch64.
+#
+# Two-layer cache, so an ordinary push doesn't pay the full toolchain-install
+# + DD-download cost every time:
+#   1. the toolchain image (docker/mdsplus/Dockerfile) — keyed on its hash.
+#      A miss means re-running the MDSplus/Java/DD-toolchain package install.
+#   2. the baked DD model tree (build-mdsplus/) — keyed on the DD version
+#      plus the model-build inputs (ALBuildDataDictionary.cmake,
+#      models/mdsplus/CMakeLists.txt). A hit restores the whole configured
+#      build directory (including the generated ids.xml and the model-tree
+#      files under build-mdsplus/models/mdsplus), so the configure step is
+#      skipped entirely on a hit — CMake's own dependency tracking then only
+#      rebuilds C++ sources that actually changed.
+
+on:
+  push:
+  pull_request:
+
+env:
+  DD_VERSION: "4.1.1"
+  IMAGE_TAG: imas-core-mdsplus:ci
+
+jobs:
+  mdsplus-contract:
+    name: MDSplus contract suite (aarch64, non-blocking)
+    runs-on: ubuntu-24.04-arm
+    continue-on-error: true  # informational leg, not a gate — for now
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # git describe needs full history for the version macro
+
+      - name: Cache toolchain image (layer 1 — keyed on Dockerfile)
+        id: cache-image
+        uses: actions/cache@v4
+        with:
+          path: /tmp/mdsplus-image.tar
+          key: mdsplus-image-${{ hashFiles('docker/mdsplus/Dockerfile') }}
+
+      - name: Build toolchain image
+        if: steps.cache-image.outputs.cache-hit != 'true'
+        run: |
+          docker build -f docker/mdsplus/Dockerfile -t "${IMAGE_TAG}" docker/mdsplus
+          docker save "${IMAGE_TAG}" -o /tmp/mdsplus-image.tar
+
+      - name: Load cached toolchain image
+        if: steps.cache-image.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/mdsplus-image.tar
+
+      - name: Cache baked DD model tree (layer 2 — keyed on DD version + model-build inputs)
+        id: cache-model
+        uses: actions/cache@v4
+        with:
+          path: build-mdsplus
+          key: mdsplus-model-${{ env.DD_VERSION }}-${{ hashFiles('common/cmake/ALBuildDataDictionary.cmake', 'models/mdsplus/CMakeLists.txt') }}
+
+      - name: Configure (bakes the DD model tree on a cache miss)
+        # The `mdsplus` preset (CMakePresets.json) carries the backend/model/
+        # test flags and the build-mdsplus binary dir; only the DD pin stays
+        # here, next to the cache key it feeds.
+        if: steps.cache-model.outputs.cache-hit != 'true'
+        run: >
+          docker run --rm --platform linux/arm64
+          -v "$PWD":/workspace -w /workspace
+          "${IMAGE_TAG}" bash -c "
+          cmake --preset mdsplus -DDD_VERSION=${DD_VERSION}
+          "
+
+      - name: Build contract suite
+        run: >
+          docker run --rm --platform linux/arm64
+          -v "$PWD":/workspace -w /workspace
+          "${IMAGE_TAG}" bash -c "
+          cmake --build --preset mdsplus
+          "
+
+      - name: Verify baked DD model tree is present (cache-hit and cache-miss paths)
+        run: |
+          set -euo pipefail
+          # ids_model.datafile is legitimately 0 bytes for a model tree (all
+          # structure lives in .tree/.characteristics; a model carries no
+          # data), so it is checked for existence only.
+          for f in ids_model.tree ids_model.characteristics; do
+            if [ ! -s "build-mdsplus/models/mdsplus/${f}" ]; then
+              echo "FATAL: missing/empty model file build-mdsplus/models/mdsplus/${f} — the MDSplus tier would fail with %TREE-E-FOPENR (issue #42)"
+              exit 1
+            fi
+          done
+          if [ ! -e "build-mdsplus/models/mdsplus/ids_model.datafile" ]; then
+            echo "FATAL: missing model file build-mdsplus/models/mdsplus/ids_model.datafile (issue #42)"
+            exit 1
+          fi
+          echo "Baked DD model tree complete under build-mdsplus/models/mdsplus."
+
+      - name: Run MDSplus contract suite
+        # The `mdsplus` test preset selects the tier (-L mdsplus) and points
+        # MDSPLUS_MODELS_PATH at the baked model tree under build-mdsplus/.
+        run: >
+          docker run --rm --platform linux/arm64
+          -v "$PWD":/workspace -w /workspace
+          "${IMAGE_TAG}" bash -c "
+          ctest --preset mdsplus
+          "
+
+      - name: Note
+        if: always()
+        # Block scalar, not a plain scalar: in a plain scalar ` #` starts a YAML
+        # comment even inside shell-looking quotes, truncating the command into
+        # an unterminated string (issue #43).
+        run: |
+          echo "MDSplus leg is informational (issue #12/#18). Red-by-design until the characterization baseline is triaged; promotion to a blocking gate is Task 3."

.github/workflows/sanitizers.yml

@@ -0,0 +1,61 @@
+name: Contract suite — sanitizers (non-blocking)
+
+# Decision D7 (TEST_STRATEGY.md): build the contract suite with
+# AddressSanitizer + UndefinedBehaviorSanitizer + LeakSanitizer and run it, so a
+# leak / use-after-free / overrun in the hot path is caught for free — no
+# per-test assertions. This leg is INFORMATIONAL, not a merge gate
+# (continue-on-error: true), until the baseline is triaged. LSan leak detection
+# is Linux-only, which is why this leg runs on ubuntu.
+
+# push is limited to develop so a PR from an in-repo branch runs the leg once,
+# not twice (push + pull_request).
+on:
+  push:
+    branches: [develop]
+  pull_request:
+
+jobs:
+  asan-ubsan-lsan:
+    name: ASan/UBSan/LSan (Linux, non-blocking)
+    runs-on: ubuntu-latest
+    continue-on-error: true  # informational leg (D7), not a gate — for now
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # git describe needs full history for the version macro
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build libhdf5-dev libboost-filesystem-dev
+
+      - name: Configure (sanitized, tests on, no Python bindings)
+        # The `sanitize` preset (CMakePresets.json) sets AL_CONTRACT_SANITIZE,
+        # which instruments both libal and the test binary. Python bindings are
+        # off: a sanitized libal must not be linked into a wheel whose bindings
+        # lack the ASan runtime (see tests/contract/CMakeLists.txt).
+        run: cmake --preset sanitize
+
+      - name: Build contract suite
+        run: cmake --build --preset sanitize
+
+      - name: Run contract suite under sanitizers
+        # The `sanitize` test preset carries the ASAN/LSAN/UBSAN_OPTIONS
+        # (halt/abort_on_error=0 so the whole suite runs and reports everything
+        # at once — informational leg) and two exclusions:
+        #  * `Death` tests deliberately crash child processes (asserting today's
+        #    crash-class defects) — not a memory-safety target, and ASan would
+        #    report the intentional crash as an error.
+        #  * `CurrentlyCorrupts` tripwires pin the ASCII rank-7 DOUBLE/COMPLEX
+        #    corruption, which is UB whose manifestation ASan's memory layout
+        #    masks (the data round-trips intact under ASan), so they legitimately
+        #    fail here. They guard against rot in the blocking functional leg
+        #    (contract-tests.yml). Real leaks/UAF in the ordinary paths still
+        #    surface.
+        run: ctest --preset sanitize
+
+      - name: Note
+        if: always()
+        run: echo "Sanitizer leg is informational (D7). Triage findings before promoting it to a required check."

.github/workflows/uda-contract.yml

@@ -0,0 +1,96 @@
+name: UDA contract suite (non-blocking)
+
+# Issue #29 (parent #21): a dedicated, informational CI leg for the UDA tier
+# (tests/contract/test_uda*.cpp, TRACEABILITY.md Part 5), mirroring the
+# mdsplus-contract leg (mdsplus-contract.yml) and its rationale: UDA is one of
+# the two DD-coupled backends (CLAUDE.md), and lands as a non-blocking leg only
+# now that issue #28 has triaged the whole baseline to terminal statuses, so
+# this leg is green (modulo pinned defects) from its first run and there is
+# never a red informational leg to maintain.
+#
+# Runs on a GitHub-hosted arm64 runner: docker/uda/Dockerfile is aarch64 (the
+# pinned reference stack docker/uda/README.md documents), matching the
+# mdsplus-contract leg's own runner choice.
+#
+# One cache layer, unlike the mdsplus leg's two: the UDA image
+# (docker/uda/Dockerfile) is the pinned, source-independent reference stack
+# (UDA server + IMAS plugin source + IDSDef.xml); it does not COPY the repo, so
+# it is cached across ordinary pushes and only Dockerfile/run.sh edits bust the
+# cache. IMAS-Core itself and the IMAS server plugin are always built fresh
+# from the mounted workspace by docker/uda/run.sh, by design (README.md
+# "Design: toolchain image + build-workspace-at-runtime") — never baked into
+# the image — so there is no second, workspace-keyed cache: CMake's own
+# dependency tracking is the only reuse mdsplus's layer 2 gets from a restored
+# build-mdsplus/ directory, and the UDA leg has no equivalent artifact to
+# restore, only source it must always rebuild against.
+
+on:
+  push:
+  pull_request:
+
+env:
+  IMAGE_TAG: imas-core-uda:ci
+
+jobs:
+  uda-contract:
+    name: UDA contract suite (aarch64, non-blocking)
+    runs-on: ubuntu-24.04-arm
+    continue-on-error: true  # informational leg, not a gate
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # git describe needs full history for the version macro
+
+      - name: Cache reference-stack image (keyed on Dockerfile + run.sh)
+        id: cache-image
+        uses: actions/cache@v4
+        with:
+          path: /tmp/uda-image.tar
+          key: uda-image-${{ hashFiles('docker/uda/Dockerfile', 'docker/uda/run.sh') }}
+
+      - name: Build reference-stack image
+        if: steps.cache-image.outputs.cache-hit != 'true'
+        run: |
+          docker build --platform linux/arm64 -f docker/uda/Dockerfile -t "${IMAGE_TAG}" docker/uda
+          docker save "${IMAGE_TAG}" -o /tmp/uda-image.tar
+
+      - name: Load cached reference-stack image
+        if: steps.cache-image.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/uda-image.tar
+
+      - name: Verify pinned stack identifiers match TRACEABILITY Part 5 header
+        run: |
+          set -euo pipefail
+          uda_server=$(docker inspect -f '{{ index .Config.Labels "org.iter.imas-core.uda-server-version" }}' "${IMAGE_TAG}")
+          uda_plugins=$(docker inspect -f '{{ index .Config.Labels "org.iter.imas-core.uda-plugins-version" }}' "${IMAGE_TAG}")
+          uda_plugins_commit=$(docker inspect -f '{{ index .Config.Labels "org.iter.imas-core.uda-plugins-commit" }}' "${IMAGE_TAG}")
+          dd_version=$(docker inspect -f '{{ index .Config.Labels "org.iter.imas-core.dd-version" }}' "${IMAGE_TAG}")
+          echo "Image labels: uda-server=${uda_server} uda-plugins=${uda_plugins}@${uda_plugins_commit} dd=${dd_version}"
+          header=tests/contract/TRACEABILITY.md
+          grep -q "tag \*\*${uda_server}\*\*" "${header}"
+          grep -q "tag \*\*${uda_plugins}\*\*" "${header}"
+          grep -q "commit \*\*\`${uda_plugins_commit}\`\*\*" "${header}"
+          grep -q "\*\*${dd_version}\*\*" "${header}"
+          echo "Image stack identifiers match ${header}'s Part 5 pinned-reference-stack table."
+
+      # AL_UDA_DEDICATED_CI=1: inside the dedicated reference-stack job a
+      # server bootstrap failure must fail the job, not skip every test —
+      # uda-run.sh makes the listener wait and the uda_cli ping fatal, and
+      # fails unless a nonzero number of UDA tests actually executed
+      # (issue #41). Developer builds without the flag keep skip semantics.
+      - name: Run the UDA contract tier
+        run: >
+          docker run --rm --platform linux/arm64
+          -v "$PWD":/workspace -w /workspace
+          -e AL_UDA_DEDICATED_CI=1
+          "${IMAGE_TAG}" uda-run.sh
+
+      - name: Note
+        if: always()
+        # Block scalar, not a plain scalar: in a plain scalar ` #` starts a YAML
+        # comment even inside shell-looking quotes, truncating the command into
+        # an unterminated string (issue #43).
+        run: |
+          echo "UDA leg is informational (issue #21/#29). Red-by-design only for un-pinned defects; TRACEABILITY.md Part 5 (issue #28) records the pinned baseline this leg should stay green against."