From ab65e703fc6f95c4ba605c815038eb159f08bedf Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Mon, 29 Jun 2026 23:14:40 -0500
Subject: [PATCH 1/7] tests: add CMake-driven equivalence test harness

Introduce a declarative way to register equivalence/determinism tests so
that adding one is a single CMake call rather than a copy-and-edit shell
script.

- codes_add_equivalence_test() registers a test that runs a model binary
  two or more times and asserts a marker line ("Net Events Processed" by
  default) is identical across runs. REPEAT covers reproducibility;
  VARIANTS covers comparisons such as seq vs optimistic (--sync=1 vs
  --sync=3).
- equivalence-run.sh is the generic runner behind it: each run executes
  in its own run-N/ subdir (so fixed relative output paths don't
  collide), greps the marker from each run, and diffs them.
- run-test.sh.in now accepts a full command with arguments, not just a
  single legacy per-scenario script.

Migrate example-ping-pong-determinism.sh as the first user of the helper
and drop the standalone script.
---
 tests/CMakeLists.txt                   | 79 ++++++++++++++++++++-
 tests/equivalence-run.sh               | 95 ++++++++++++++++++++++++++
 tests/example-ping-pong-determinism.sh | 39 -----------
 tests/run-test.sh.in                   |  9 ++-
 4 files changed, 181 insertions(+), 41 deletions(-)
 create mode 100755 tests/equivalence-run.sh
 delete mode 100755 tests/example-ping-pong-determinism.sh

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index ec0acdeb..dc1595e0 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -2,6 +2,73 @@ enable_testing()
 
 configure_file(run-test.sh.in run-test.sh)
 
+# codes_add_equivalence_test — register an equivalence/determinism test.
+#
+# Runs a model binary two or more times and asserts a marker line (default
+# "Net Events Processed") is identical across runs. Replaces the copy-and-edit
+# per-scenario shell scripts: adding a test is one call here, no new file.
+#
+#   codes_add_equivalence_test(
+#       NAME     <ctest name>
+#       BINARY   <CMake target>            # e.g. tutorial-synthetic-ping-pong
+#       CONFIG   <path under build dir>     # e.g. doc/example/tutorial-ping-pong.conf
+#       [NP      <ranks>]                   # default 3
+#       [ARGS    <args shared by all runs>]
+#       [REPEAT  <n>]                       # default 2; identical runs (reproducibility)
+#       [VARIANTS "<extra args run 1>" "<extra args run 2>" ...]  # one run each, appended
+#       [MARKER  <line to compare>]         # default "Net Events Processed"
+#       [SETUP   <script under source dir>] # sourced before runs (env + conf generation)
+#   )
+#
+# REPEAT and VARIANTS are mutually exclusive ways to describe the runs:
+# REPEAT for "same command N times", VARIANTS when only a small fragment differs
+# (e.g. VARIANTS "--sync=1" "--sync=3" for a seq-vs-optimistic check).
+function(codes_add_equivalence_test)
+    cmake_parse_arguments(T "" "NAME;BINARY;NP;CONFIG;MARKER;REPEAT;SETUP" "ARGS;VARIANTS" ${ARGN})
+
+    if(NOT T_NAME OR NOT T_BINARY OR NOT T_CONFIG)
+        message(FATAL_ERROR "codes_add_equivalence_test: NAME, BINARY and CONFIG are required")
+    endif()
+    if(NOT T_NP)
+        set(T_NP 3)
+    endif()
+    if(NOT T_MARKER)
+        set(T_MARKER "Net Events Processed")
+    endif()
+    if(NOT T_REPEAT)
+        set(T_REPEAT 2)
+    endif()
+
+    set(_bin    "$<TARGET_FILE:${T_BINARY}>")
+    set(_config "${CODES_BINARY_DIR}/${T_CONFIG}")
+    set(_launch ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS})
+
+    set(_cmd "")
+    if(T_VARIANTS)
+        foreach(_extra IN LISTS T_VARIANTS)
+            separate_arguments(_extra_list UNIX_COMMAND "${_extra}")
+            list(APPEND _cmd @@ ${_launch} "${_bin}" ${T_ARGS} ${_extra_list}
+                             ${MPIEXEC_POSTFLAGS} -- "${_config}")
+        endforeach()
+    else()
+        foreach(_i RANGE 1 ${T_REPEAT})
+            list(APPEND _cmd @@ ${_launch} "${_bin}" ${T_ARGS}
+                             ${MPIEXEC_POSTFLAGS} -- "${_config}")
+        endforeach()
+    endif()
+
+    set(_setup "")
+    if(T_SETUP)
+        set(_setup --setup "${CMAKE_CURRENT_SOURCE_DIR}/${T_SETUP}")
+    endif()
+
+    add_test(NAME ${T_NAME}
+        COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
+                bash "${CMAKE_CURRENT_SOURCE_DIR}/equivalence-run.sh"
+                --marker "${T_MARKER}" ${_setup} ${_cmd}
+        WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+endfunction()
+
 # Unfortunatelly, CMake doesn't support iteration of a key-pair structure,
 # otherwise the following lists could be easily compressed into a single
 # list/dictionary/structure. Instead each C file name **MUST** match each
@@ -84,7 +151,7 @@ set(test-shell-files
     modelnet-test-fattree-synthetic.sh
     modelnet-test-slimfly-synthetic.sh
     workload/codes-workload-test.sh
-    example-ping-pong-determinism.sh
+    # example-ping-pong-determinism.sh migrated to codes_add_equivalence_test below
     example-ping-pong-surrogate-1.sh
     example-ping-pong-surrogate-2.sh
     example-ping-pong-surrogate-3.sh
@@ -112,3 +179,13 @@ foreach(testname ${test-shell-files})
         COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh" "${CMAKE_CURRENT_SOURCE_DIR}/${testname}"
         WORKING_DIRECTORY "${CODES_BINARY_DIR}")
 endforeach()
+
+# Equivalence / determinism tests (replacing per-scenario shell scripts).
+# example-ping-pong-determinism.sh: run the optimistic sim twice, compare
+# committed-event counts (reproducibility).
+codes_add_equivalence_test(
+    NAME   example-ping-pong-determinism
+    BINARY tutorial-synthetic-ping-pong
+    NP     3
+    ARGS   --sync=3 --num_messages=10 --payload_sz=8192
+    CONFIG doc/example/tutorial-ping-pong.conf)
diff --git a/tests/equivalence-run.sh b/tests/equivalence-run.sh
new file mode 100755
index 00000000..297f9efc
--- /dev/null
+++ b/tests/equivalence-run.sh
@@ -0,0 +1,95 @@
+#!/bin/bash
+#
+# Generic equivalence runner for CODES tests.
+#
+# Runs two (or more) commands, greps a marker line from each run's stdout, and
+# asserts the marked lines are identical across every run. Used for both:
+#   - reproducibility  (same command run N times -> result must not vary), and
+#   - seq-vs-optimistic (same args, differing --sync -> committed work must match).
+#
+# It is driven entirely from CMake by codes_add_equivalence_test(); it is not
+# meant to be hand-edited per test. Each run executes in its own run-N/ subdir
+# so that runs writing to fixed relative output paths don't collide.
+#
+# Usage:
+#   equivalence-run.sh --marker "Net Events Processed" [--setup <script>] \
+#       @@ <cmd for run 1...> @@ <cmd for run 2...> [ @@ <run 3...> ]
+#
+# '@@' separates runs. A run's own '--' (ROSS opts | .conf) stays intact within
+# its segment. --setup names a script that is *sourced* before any run, so it
+# may export environment variables and/or generate config files in the sandbox.
+
+set -u
+
+marker="Net Events Processed"
+setup=""
+
+# Leading options, up to the first run separator.
+while [[ $# -gt 0 && "$1" != "@@" ]]; do
+    case "$1" in
+        --marker) marker="$2"; shift 2 ;;
+        --setup)  setup="$2";  shift 2 ;;
+        *) echo "equivalence-run.sh: unknown option '$1'" >&2; exit 2 ;;
+    esac
+done
+[[ "${1:-}" == "@@" ]] && shift
+
+# Sourced (not executed) so exported vars and generated confs are visible to runs.
+if [[ -n "$setup" ]]; then
+    # shellcheck disable=SC1090
+    source "$setup"
+fi
+
+run_idx=0
+cmd=()
+outputs=()
+
+run_one() {
+    run_idx=$((run_idx + 1))
+    local dir="run-${run_idx}"
+    mkdir -p "$dir"
+    local out="${dir}/model-output.txt"
+    local errf="${dir}/model-output-error.txt"
+
+    echo "+ run ${run_idx}: ${cmd[*]}" >&2
+    ( cd "$dir" && "${cmd[@]}" ) > "$out" 2> "$errf"
+    local rc=$?
+    if [[ $rc -ne 0 ]]; then
+        echo "equivalence-run.sh: run ${run_idx} exited with $rc" >&2
+        cat "$errf" >&2
+        exit $rc
+    fi
+    if ! grep -q "$marker" "$out"; then
+        echo "equivalence-run.sh: run ${run_idx} produced no '$marker' line" \
+             "(did the simulation produce output?)" >&2
+        exit 1
+    fi
+    outputs+=("$out")
+    cmd=()
+}
+
+for tok in "$@"; do
+    if [[ "$tok" == "@@" ]]; then
+        run_one
+    else
+        cmd+=("$tok")
+    fi
+done
+[[ ${#cmd[@]} -gt 0 ]] && run_one
+
+if [[ ${#outputs[@]} -lt 2 ]]; then
+    echo "equivalence-run.sh: need at least 2 runs to compare, got ${#outputs[@]}" >&2
+    exit 2
+fi
+
+# Compare every run's marker line against the first.
+ref="${outputs[0]}"
+status=0
+for out in "${outputs[@]:1}"; do
+    if ! diff <(grep "$marker" "$ref") <(grep "$marker" "$out") >&2; then
+        echo "equivalence-run.sh: MISMATCH on '$marker' between ${ref} and ${out}" \
+             "-- the runs are not equivalent" >&2
+        status=1
+    fi
+done
+exit $status
diff --git a/tests/example-ping-pong-determinism.sh b/tests/example-ping-pong-determinism.sh
deleted file mode 100755
index 58c2c973..00000000
--- a/tests/example-ping-pong-determinism.sh
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/bin/bash
-
-if [[ -z $bindir ]] ; then
-    echo bindir variable not set
-    exit 1
-fi
-
-# Running simulation twice with the same parameters
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=10 --payload_sz=8192 \
-    -- "$bindir/doc/example/tutorial-ping-pong.conf" \
-    > model-output-1.txt 2> model-output-1-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=10 --payload_sz=8192 \
-    -- "$bindir/doc/example/tutorial-ping-pong.conf" \
-    > model-output-2.txt 2> model-output-2-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that there is actual output
-grep 'Net Events Processed' model-output-1.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# This checks for the number of events processed. If they are different, then
-# the simulation is not deterministic (so this should fail!). As always, just
-# a unit test
-diff <(grep 'Net Events Processed' model-output-1.txt) \
-    <(grep 'Net Events Processed' model-output-2.txt)
-err=$?
-if [[ $err -ne 0 ]]; then
-    >&2 echo "The number of net events processed does not coincide, ie," \
-        "the simulation is not deterministic"
-    exit $err
-fi
diff --git a/tests/run-test.sh.in b/tests/run-test.sh.in
index be706268..b2b566cd 100755
--- a/tests/run-test.sh.in
+++ b/tests/run-test.sh.in
@@ -27,7 +27,14 @@ tmpdir="$(mktemp -d testing-output/test-XXXXXX)"
 pushd $tmpdir
 
 # running experiment
-bash -x "$1"
+# - one argument: a legacy per-scenario test script (the historical form)
+# - more than one: a generic command + args (e.g. the equivalence runner),
+#   driven by codes_add_equivalence_test()
+if [[ $# -gt 1 ]]; then
+    "$@"
+else
+    bash -x "$1"
+fi
 
 # checking for exit error
 err=$?

From 0f8a9e95ababd56b83cae9ecbd9498a47147bb1b Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Mon, 29 Jun 2026 23:36:58 -0500
Subject: [PATCH 2/7] tests: migrate single-run shell tests to a CMake helper

Add codes_add_run_test() for single-run smoke/unit tests: run a binary
once under MPI and pass on clean exit. The caller supplies the full
post-binary argument list, which absorbs the various ways CODES binaries
take their config (positional, "-- <conf>", "--codes-config=",
"--conf=", or none).

Convert the per-scenario shell scripts to declarative calls and delete
them: lp-io, jobmap, map-ctx, resource, lsm, rc-stack, the modelnet-*
topology family, the synthetic-traffic binaries, and the workload test.
Two fixes fall out of the migration:

- rc-stack-test ran the wrong binary (modelnet-simplep2p-test) due to a
  copy-paste error; it now runs rc-stack-test.
- modelnet-prio-sched ran both schedulers in one script; split into
  separate seq (--sync=1) and opt (--sync=3) tests.

Tests with custom logic (mapping_test) or held back for review stay as
shell scripts for now.
---
 tests/CMakeLists.txt                       | 108 +++++++++++++++------
 tests/jobmap-test.sh                       |  12 ---
 tests/lp-io-test.sh                        |   7 --
 tests/lsm-test.sh                          |  12 ---
 tests/map-ctx-test.sh                      |  12 ---
 tests/modelnet-p2p-bw-loggp.sh             |   7 --
 tests/modelnet-prio-sched-test.sh          |  19 ----
 tests/modelnet-simplep2p-test.sh           |  12 ---
 tests/modelnet-test-dragonfly-synthetic.sh |  11 ---
 tests/modelnet-test-dragonfly.sh           |   7 --
 tests/modelnet-test-em.sh                  |   7 --
 tests/modelnet-test-fattree-synthetic.sh   |  19 ----
 tests/modelnet-test-loggp.sh               |   7 --
 tests/modelnet-test-slimfly-synthetic.sh   |  11 ---
 tests/modelnet-test-slimfly.sh             |   7 --
 tests/modelnet-test-torus.sh               |   7 --
 tests/modelnet-test.sh                     |   7 --
 tests/rc-stack-test.sh                     |  12 ---
 tests/resource-test.sh                     |  12 ---
 tests/workload/codes-workload-test.sh      |  11 ---
 20 files changed, 78 insertions(+), 229 deletions(-)
 delete mode 100755 tests/jobmap-test.sh
 delete mode 100755 tests/lp-io-test.sh
 delete mode 100755 tests/lsm-test.sh
 delete mode 100755 tests/map-ctx-test.sh
 delete mode 100755 tests/modelnet-p2p-bw-loggp.sh
 delete mode 100755 tests/modelnet-prio-sched-test.sh
 delete mode 100755 tests/modelnet-simplep2p-test.sh
 delete mode 100755 tests/modelnet-test-dragonfly-synthetic.sh
 delete mode 100755 tests/modelnet-test-dragonfly.sh
 delete mode 100755 tests/modelnet-test-em.sh
 delete mode 100755 tests/modelnet-test-fattree-synthetic.sh
 delete mode 100755 tests/modelnet-test-loggp.sh
 delete mode 100755 tests/modelnet-test-slimfly-synthetic.sh
 delete mode 100755 tests/modelnet-test-slimfly.sh
 delete mode 100755 tests/modelnet-test-torus.sh
 delete mode 100755 tests/modelnet-test.sh
 delete mode 100755 tests/rc-stack-test.sh
 delete mode 100755 tests/resource-test.sh
 delete mode 100755 tests/workload/codes-workload-test.sh

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index dc1595e0..531d0abd 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -69,6 +69,37 @@ function(codes_add_equivalence_test)
         WORKING_DIRECTORY "${CODES_BINARY_DIR}")
 endfunction()
 
+# codes_add_run_test — register a single-run smoke / unit test.
+#
+# Runs a model or test binary once under MPI; the test passes on clean exit
+# (run-test.sh additionally fails if the binary leaves an empty ross.csv). The
+# caller supplies the full post-binary argument list, which absorbs the various
+# ways CODES binaries take their config: positional, "-- <conf>",
+# "--codes-config=<conf>", "--conf=<conf>", or none. Config files live in the
+# source tree, so reference them as ${CMAKE_CURRENT_SOURCE_DIR}/... (tests/) or
+# ${CMAKE_SOURCE_DIR}/... (elsewhere).
+#
+#   codes_add_run_test(
+#       NAME   <ctest name>
+#       BINARY <CMake target>
+#       [NP    <ranks>]                 # default 1
+#       [ARGS  <full args after the binary>]
+#   )
+function(codes_add_run_test)
+    cmake_parse_arguments(T "" "NAME;BINARY;NP" "ARGS" ${ARGN})
+    if(NOT T_NAME OR NOT T_BINARY)
+        message(FATAL_ERROR "codes_add_run_test: NAME and BINARY are required")
+    endif()
+    if(NOT T_NP)
+        set(T_NP 1)
+    endif()
+    add_test(NAME ${T_NAME}
+        COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
+                ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS}
+                "$<TARGET_FILE:${T_BINARY}>" ${T_ARGS} ${MPIEXEC_POSTFLAGS}
+        WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+endfunction()
+
 # Unfortunatelly, CMake doesn't support iteration of a key-pair structure,
 # otherwise the following lists could be easily compressed into a single
 # list/dictionary/structure. Instead each C file name **MUST** match each
@@ -120,38 +151,14 @@ target_link_libraries(codes-workload-test PUBLIC codes)
 
 # Tests are also not consistent with the files to compile, but
 # that's ok, there are more tests than binary files
+# Scripts still run as per-scenario shell files. Most single-run tests were
+# migrated to codes_add_run_test() and the simple determinism test to
+# codes_add_equivalence_test() (both below). What remains here either has
+# custom logic, is held back for review, or is migrated in a later chunk.
 set(test-shell-files
-    # All binaries have an associated sh test script
-    lp-io-test.sh
+    # mapping_test diffs binary output against tests/expected/mapping_test.out
     mapping_test.sh
-    jobmap-test.sh
-    map-ctx-test.sh
-    modelnet-prio-sched-test.sh
-    modelnet-test-dragonfly.sh
-    modelnet-test.sh
-    resource-test.sh
-    modelnet-p2p-bw-loggp.sh
-    modelnet-simplep2p-test.sh
-    rc-stack-test.sh
-    lsm-test.sh
-    # These tests correspond to archived models / no binaries are being generated by CMake
-    #modelnet-test-dragonfly-custom-synthetic.sh
-    #modelnet-test-dragonfly-dally-synthetic.sh
-    #modelnet-test-dragonfly-plus-synthetic.sh
-    modelnet-test-torus.sh
-    modelnet-test-em.sh
-    modelnet-test-loggp.sh
-    modelnet-test-slimfly.sh
-    # These tests are not supported by the makefile/autoconf machinery either
-    #modelnet-test-dragonfly-custom-traces.sh
-    #modelnet-test-dragonfly-traces.sh
-    #modelnet-test-slimfly-traces.sh
-    #modelnet-test-torus-traces.sh
-    modelnet-test-dragonfly-synthetic.sh
-    modelnet-test-fattree-synthetic.sh
-    modelnet-test-slimfly-synthetic.sh
-    workload/codes-workload-test.sh
-    # example-ping-pong-determinism.sh migrated to codes_add_equivalence_test below
+    # Surrogate / no-logging determinism tests -- migrated via SETUP next chunk.
     example-ping-pong-surrogate-1.sh
     example-ping-pong-surrogate-2.sh
     example-ping-pong-surrogate-3.sh
@@ -189,3 +196,44 @@ codes_add_equivalence_test(
     NP     3
     ARGS   --sync=3 --num_messages=10 --payload_sz=8192
     CONFIG doc/example/tutorial-ping-pong.conf)
+
+# Single-run smoke / unit tests (migrated from per-scenario shell scripts).
+# Config files live in the source tree; _tconf/_nwconf point at the two homes.
+set(_tconf "${CMAKE_CURRENT_SOURCE_DIR}/conf")
+set(_nwconf "${CMAKE_SOURCE_DIR}/src/network-workloads/conf")
+
+codes_add_run_test(NAME lp-io-test    BINARY lp-io-test    ARGS --sync=1)
+# rc-stack-test is a serial unit test (no config, no args); the old script ran
+# the wrong binary (modelnet-simplep2p-test) -- a copy-paste error, fixed here.
+codes_add_run_test(NAME rc-stack-test BINARY rc-stack-test)
+# modelnet-prio-sched ran both schedulers in one script; split into two tests.
+codes_add_run_test(NAME modelnet-prio-sched-test-seq BINARY modelnet-prio-sched-test
+    NP 1 ARGS --sync=1 -- "${_tconf}/modelnet-prio-sched-test.conf")
+codes_add_run_test(NAME modelnet-prio-sched-test-opt BINARY modelnet-prio-sched-test
+    NP 2 ARGS --sync=3 -- "${_tconf}/modelnet-prio-sched-test.conf")
+codes_add_run_test(NAME jobmap-test   BINARY jobmap-test   ARGS "${_tconf}/jobmap-test-list.conf")
+codes_add_run_test(NAME map-ctx-test  BINARY map-ctx-test  ARGS "${_tconf}/map-ctx-test.conf")
+codes_add_run_test(NAME resource-test BINARY resource-test ARGS --sync=1 "--codes-config=${_tconf}/buffer_test.conf")
+codes_add_run_test(NAME lsm-test      BINARY lsm-test      ARGS --sync=1 "--conf=${_tconf}/lsm-test.conf")
+codes_add_run_test(NAME modelnet-simplep2p-test BINARY modelnet-simplep2p-test
+    ARGS --sync=1 -- "${_tconf}/modelnet-test-simplep2p.conf")
+codes_add_run_test(NAME modelnet-p2p-bw-loggp BINARY modelnet-p2p-bw
+    ARGS --sync=1 -- "${_tconf}/modelnet-p2p-bw-loggp.conf")
+codes_add_run_test(NAME codes-workload-test BINARY codes-workload-test
+    ARGS --sync=1 "${CMAKE_CURRENT_SOURCE_DIR}/workload/codes-workload-test.conf")
+
+# modelnet-test binary exercised against one config per topology.
+codes_add_run_test(NAME modelnet-test           BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test.conf")
+codes_add_run_test(NAME modelnet-test-dragonfly BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test-dragonfly.conf")
+codes_add_run_test(NAME modelnet-test-torus     BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test-torus.conf")
+codes_add_run_test(NAME modelnet-test-em        BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test-em.conf")
+codes_add_run_test(NAME modelnet-test-loggp     BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test-loggp.conf")
+codes_add_run_test(NAME modelnet-test-slimfly   BINARY modelnet-test ARGS --sync=1 -- "${_tconf}/modelnet-test-slimfly.conf")
+
+# Synthetic-traffic binaries.
+codes_add_run_test(NAME modelnet-test-dragonfly-synthetic BINARY model-net-synthetic
+    ARGS --sync=1 --num_messages=1 -- "${_nwconf}/modelnet-synthetic-dragonfly.conf")
+codes_add_run_test(NAME modelnet-test-fattree-synthetic BINARY model-net-synthetic-fattree
+    ARGS --sync=1 -- "${_nwconf}/modelnet-synthetic-fattree.conf")
+codes_add_run_test(NAME modelnet-test-slimfly-synthetic BINARY model-net-synthetic-slimfly
+    ARGS --sync=1 -- "${_nwconf}/modelnet-synthetic-slimfly-min.conf")
diff --git a/tests/jobmap-test.sh b/tests/jobmap-test.sh
deleted file mode 100755
index a56e1698..00000000
--- a/tests/jobmap-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [[ -z $srcdir ]] ; then
-    echo srcdir variable not set
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-"$bindir"/tests/jobmap-test "$srcdir"/tests/conf/jobmap-test-list.conf
diff --git a/tests/lp-io-test.sh b/tests/lp-io-test.sh
deleted file mode 100755
index c9a6d4fa..00000000
--- a/tests/lp-io-test.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/lp-io-test --sync=1
diff --git a/tests/lsm-test.sh b/tests/lsm-test.sh
deleted file mode 100755
index 168a2411..00000000
--- a/tests/lsm-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [ -z $srcdir ]; then
-    echo srcdir variable not set.
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/lsm-test --sync=1 --conf="$srcdir"/tests/conf/lsm-test.conf
diff --git a/tests/map-ctx-test.sh b/tests/map-ctx-test.sh
deleted file mode 100755
index def90c7f..00000000
--- a/tests/map-ctx-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [[ -z $srcdir ]] ; then
-    echo srcdir variable not set
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/map-ctx-test "$srcdir"/tests/conf/map-ctx-test.conf
diff --git a/tests/modelnet-p2p-bw-loggp.sh b/tests/modelnet-p2p-bw-loggp.sh
deleted file mode 100755
index b49c80e9..00000000
--- a/tests/modelnet-p2p-bw-loggp.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-p2p-bw --sync=1 -- "$srcdir"/tests/conf/modelnet-p2p-bw-loggp.conf
diff --git a/tests/modelnet-prio-sched-test.sh b/tests/modelnet-prio-sched-test.sh
deleted file mode 100755
index 1d033d97..00000000
--- a/tests/modelnet-prio-sched-test.sh
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-prio-sched-test --sync=1 -- \
-    $srcdir/tests/conf/modelnet-prio-sched-test.conf
-err=$?
-if [[ $err -ne 0 ]]; then
-    exit $err
-fi
-
-mpirun -np 2 "$bindir"/tests/modelnet-prio-sched-test --sync=3 -- \
-    $srcdir/tests/conf/modelnet-prio-sched-test.conf
-err=$?
-if [[ $err -ne 0 ]]; then
-    exit $err
-fi
diff --git a/tests/modelnet-simplep2p-test.sh b/tests/modelnet-simplep2p-test.sh
deleted file mode 100755
index 94e4cada..00000000
--- a/tests/modelnet-simplep2p-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [[ -z $srcdir ]] ; then
-    echo srcdir variable not set
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-simplep2p-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-simplep2p.conf
diff --git a/tests/modelnet-test-dragonfly-synthetic.sh b/tests/modelnet-test-dragonfly-synthetic.sh
deleted file mode 100755
index a5b4b072..00000000
--- a/tests/modelnet-test-dragonfly-synthetic.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Binaries generated by CMake are located in a different place
-# to those of autoconf
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=src/network-workloads
-else
-    bindir="$bindir"/src
-fi
-
-mpirun -np 1 "$bindir"/model-net-synthetic --sync=1 --num_messages=1 -- "$srcdir"/src/network-workloads/conf/modelnet-synthetic-dragonfly.conf
diff --git a/tests/modelnet-test-dragonfly.sh b/tests/modelnet-test-dragonfly.sh
deleted file mode 100755
index 8731a87a..00000000
--- a/tests/modelnet-test-dragonfly.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-dragonfly.conf
diff --git a/tests/modelnet-test-em.sh b/tests/modelnet-test-em.sh
deleted file mode 100755
index d4411d6d..00000000
--- a/tests/modelnet-test-em.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-em.conf
diff --git a/tests/modelnet-test-fattree-synthetic.sh b/tests/modelnet-test-fattree-synthetic.sh
deleted file mode 100755
index 3f7744d9..00000000
--- a/tests/modelnet-test-fattree-synthetic.sh
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/bin/bash
-
-if [ -z $srcdir ]; then
-         echo srcdir variable not set.
-              exit 1
- fi
-
-# Binaries generated by CMake are located in a different place
-# to those of autoconf
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=src/network-workloads
-else
-    bindir="$bindir"/src
-fi
-
-mpirun -np 1 "$bindir"/model-net-synthetic-fattree --sync=1 -- "$srcdir"/src/network-workloads/conf/modelnet-synthetic-fattree.conf
-
-#source $srcdir/tests/download-traces.sh
-#src/network-workloads/model-net-mpi-replay --sync=1 --num_net_traces=27 --workload_file=/tmp/df_AMG_n27_dumpi/dumpi-2014.03.03.14.55.00- --workload_type="dumpi" -- $srcdir/src/network-workloads/conf/modelnet-mpi-test-fattree.conf 
diff --git a/tests/modelnet-test-loggp.sh b/tests/modelnet-test-loggp.sh
deleted file mode 100755
index 2eef34bd..00000000
--- a/tests/modelnet-test-loggp.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-loggp.conf
diff --git a/tests/modelnet-test-slimfly-synthetic.sh b/tests/modelnet-test-slimfly-synthetic.sh
deleted file mode 100755
index 21ea0458..00000000
--- a/tests/modelnet-test-slimfly-synthetic.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Binaries generated by CMake are located in a different place
-# to those of autoconf
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=src/network-workloads
-else
-    bindir="$bindir"/src
-fi
-
-mpirun -np 1 "$bindir"/model-net-synthetic-slimfly --sync=1 -- "$srcdir"/src/network-workloads/conf/modelnet-synthetic-slimfly-min.conf
diff --git a/tests/modelnet-test-slimfly.sh b/tests/modelnet-test-slimfly.sh
deleted file mode 100755
index 2a5b6a8c..00000000
--- a/tests/modelnet-test-slimfly.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-slimfly.conf
diff --git a/tests/modelnet-test-torus.sh b/tests/modelnet-test-torus.sh
deleted file mode 100755
index 2b102bcc..00000000
--- a/tests/modelnet-test-torus.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test-torus.conf
diff --git a/tests/modelnet-test.sh b/tests/modelnet-test.sh
deleted file mode 100755
index 248f5117..00000000
--- a/tests/modelnet-test.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-test --sync=1 -- "$srcdir"/tests/conf/modelnet-test.conf
diff --git a/tests/rc-stack-test.sh b/tests/rc-stack-test.sh
deleted file mode 100755
index ec254542..00000000
--- a/tests/rc-stack-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [[ -z $srcdir ]] ; then
-    echo srcdir variable not set
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/modelnet-simplep2p-test
diff --git a/tests/resource-test.sh b/tests/resource-test.sh
deleted file mode 100755
index 4125e0f8..00000000
--- a/tests/resource-test.sh
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/bin/bash
-
-if [[ -z $srcdir ]] ; then
-    echo srcdir variable not set
-    exit 1
-fi
-
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=.
-fi
-
-mpirun -np 1 "$bindir"/tests/resource-test --sync=1 --codes-config="$srcdir"/tests/conf/buffer_test.conf
diff --git a/tests/workload/codes-workload-test.sh b/tests/workload/codes-workload-test.sh
deleted file mode 100755
index a594716b..00000000
--- a/tests/workload/codes-workload-test.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Binaries generated by CMake are located in a different place
-# to those of autoconf
-if [ -z $GENERATED_USING_CMAKE ]; then
-    bindir=tests/workload
-else
-    bindir=$bindir/tests
-fi
-
-"$bindir"/codes-workload-test --sync=1 "$srcdir"/tests/workload/codes-workload-test.conf

From e6f2477c2dce02e228bf9c1664864e7af5991430 Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Tue, 30 Jun 2026 01:25:20 -0500
Subject: [PATCH 3/7] tests: migrate surrogate/no-logging tests, generalize the
 runner

Generalize equivalence-run.sh into a staged runner that also drives
single-run smoke tests. New options, threaded through both CMake helpers:

- --setup sources a script inside each run dir before the run, so it can
  export env vars and generate the config there; CONFIG/ARGS then
  reference the generated file by bare name.
- --require asserts a line is present in every run's output (e.g.
  "Network switch completed", proving the surrogate actually engaged).
- codes_add_run_test() gains SETUP/MARKER and routes through the runner
  when either is set.

Add the setup scripts (no-logging, surrogate-determinism freeze and
no-freeze) and migrate the no-logging and surrogate-determinism tests to
the helpers, dropping their standalone scripts.

The surrogate-1/2/3 scripts stay as-is: they are cross-config
comparisons (surrogate vs high-fidelity, freeze vs non-freeze) with
custom sed-normalized diffs, not determinism checks. Their final
packet-count check is a no-op (it execs the *.txt files instead of
listing them); fixing that is left to its own commit.
---
 tests/CMakeLists.txt                          | 103 +++++++++++++++---
 tests/equivalence-run.sh                      |  78 ++++++++-----
 tests/example-ping-pong-no-logging.sh         |  25 -----
 ...ample-ping-pong-surrogate-determinism-1.sh |  57 ----------
 ...ample-ping-pong-surrogate-determinism-2.sh |  57 ----------
 tests/no-logging-setup.sh                     |   9 ++
 tests/surrogate-determinism-freeze-setup.sh   |  15 +++
 .../surrogate-determinism-no-freeze-setup.sh  |  15 +++
 8 files changed, 177 insertions(+), 182 deletions(-)
 delete mode 100755 tests/example-ping-pong-no-logging.sh
 delete mode 100755 tests/example-ping-pong-surrogate-determinism-1.sh
 delete mode 100755 tests/example-ping-pong-surrogate-determinism-2.sh
 create mode 100644 tests/no-logging-setup.sh
 create mode 100644 tests/surrogate-determinism-freeze-setup.sh
 create mode 100644 tests/surrogate-determinism-no-freeze-setup.sh

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 531d0abd..ada50ce0 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -11,20 +11,24 @@ configure_file(run-test.sh.in run-test.sh)
 #   codes_add_equivalence_test(
 #       NAME     <ctest name>
 #       BINARY   <CMake target>            # e.g. tutorial-synthetic-ping-pong
-#       CONFIG   <path under build dir>     # e.g. doc/example/tutorial-ping-pong.conf
+#       CONFIG   <path under build dir, or bare name generated by SETUP>
 #       [NP      <ranks>]                   # default 3
 #       [ARGS    <args shared by all runs>]
 #       [REPEAT  <n>]                       # default 2; identical runs (reproducibility)
 #       [VARIANTS "<extra args run 1>" "<extra args run 2>" ...]  # one run each, appended
 #       [MARKER  <line to compare>]         # default "Net Events Processed"
-#       [SETUP   <script under source dir>] # sourced before runs (env + conf generation)
+#       [SETUP   <script under tests/>]      # sourced in each run dir (env + conf gen)
+#       [REQUIRE <line that must appear in every run's output>]  # presence only
 #   )
 #
+# With SETUP, CONFIG names the file the setup script generates in each run dir
+# (referenced by bare name), not a build-dir path.
+#
 # REPEAT and VARIANTS are mutually exclusive ways to describe the runs:
 # REPEAT for "same command N times", VARIANTS when only a small fragment differs
 # (e.g. VARIANTS "--sync=1" "--sync=3" for a seq-vs-optimistic check).
 function(codes_add_equivalence_test)
-    cmake_parse_arguments(T "" "NAME;BINARY;NP;CONFIG;MARKER;REPEAT;SETUP" "ARGS;VARIANTS" ${ARGN})
+    cmake_parse_arguments(T "" "NAME;BINARY;NP;CONFIG;MARKER;REPEAT;SETUP;REQUIRE" "ARGS;VARIANTS" ${ARGN})
 
     if(NOT T_NAME OR NOT T_BINARY OR NOT T_CONFIG)
         message(FATAL_ERROR "codes_add_equivalence_test: NAME, BINARY and CONFIG are required")
@@ -40,7 +44,14 @@ function(codes_add_equivalence_test)
     endif()
 
     set(_bin    "$<TARGET_FILE:${T_BINARY}>")
-    set(_config "${CODES_BINARY_DIR}/${T_CONFIG}")
+    # Without SETUP, CONFIG is a file under the build dir. With SETUP, the config
+    # is generated by the setup script inside each run dir, so CONFIG is the bare
+    # name it writes (resolved relative to the run dir).
+    if(T_SETUP)
+        set(_config "${T_CONFIG}")
+    else()
+        set(_config "${CODES_BINARY_DIR}/${T_CONFIG}")
+    endif()
     set(_launch ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS})
 
     set(_cmd "")
@@ -61,11 +72,15 @@ function(codes_add_equivalence_test)
     if(T_SETUP)
         set(_setup --setup "${CMAKE_CURRENT_SOURCE_DIR}/${T_SETUP}")
     endif()
+    set(_require "")
+    if(T_REQUIRE)
+        set(_require --require "${T_REQUIRE}")
+    endif()
 
     add_test(NAME ${T_NAME}
         COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
                 bash "${CMAKE_CURRENT_SOURCE_DIR}/equivalence-run.sh"
-                --marker "${T_MARKER}" ${_setup} ${_cmd}
+                --marker "${T_MARKER}" ${_require} ${_setup} ${_cmd}
         WORKING_DIRECTORY "${CODES_BINARY_DIR}")
 endfunction()
 
@@ -79,25 +94,48 @@ endfunction()
 # source tree, so reference them as ${CMAKE_CURRENT_SOURCE_DIR}/... (tests/) or
 # ${CMAKE_SOURCE_DIR}/... (elsewhere).
 #
+# With SETUP and/or MARKER the test runs through the staged runner instead:
+# SETUP is sourced inside the run dir (env + config generation; reference the
+# generated config by bare name in ARGS), and MARKER must appear in the output.
+#
 #   codes_add_run_test(
 #       NAME   <ctest name>
 #       BINARY <CMake target>
 #       [NP    <ranks>]                 # default 1
 #       [ARGS  <full args after the binary>]
+#       [SETUP <script under tests/>]    # sourced in the run dir before the run
+#       [MARKER <line that must appear in the output>]
 #   )
 function(codes_add_run_test)
-    cmake_parse_arguments(T "" "NAME;BINARY;NP" "ARGS" ${ARGN})
+    cmake_parse_arguments(T "" "NAME;BINARY;NP;SETUP;MARKER" "ARGS" ${ARGN})
     if(NOT T_NAME OR NOT T_BINARY)
         message(FATAL_ERROR "codes_add_run_test: NAME and BINARY are required")
     endif()
     if(NOT T_NP)
         set(T_NP 1)
     endif()
-    add_test(NAME ${T_NAME}
-        COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
-                ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS}
-                "$<TARGET_FILE:${T_BINARY}>" ${T_ARGS} ${MPIEXEC_POSTFLAGS}
-        WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+    set(_run ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS}
+             "$<TARGET_FILE:${T_BINARY}>" ${T_ARGS} ${MPIEXEC_POSTFLAGS})
+
+    if(T_SETUP OR T_MARKER)
+        # SETUP must be sourced and MARKER checked -> go through the staged runner.
+        set(_opts "")
+        if(T_MARKER)
+            list(APPEND _opts --marker "${T_MARKER}")
+        endif()
+        if(T_SETUP)
+            list(APPEND _opts --setup "${CMAKE_CURRENT_SOURCE_DIR}/${T_SETUP}")
+        endif()
+        add_test(NAME ${T_NAME}
+            COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
+                    bash "${CMAKE_CURRENT_SOURCE_DIR}/equivalence-run.sh"
+                    ${_opts} @@ ${_run}
+            WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+    else()
+        add_test(NAME ${T_NAME}
+            COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh" ${_run}
+            WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+    endif()
 endfunction()
 
 # Unfortunatelly, CMake doesn't support iteration of a key-pair structure,
@@ -158,13 +196,18 @@ target_link_libraries(codes-workload-test PUBLIC codes)
 set(test-shell-files
     # mapping_test diffs binary output against tests/expected/mapping_test.out
     mapping_test.sh
-    # Surrogate / no-logging determinism tests -- migrated via SETUP next chunk.
+    # surrogate-1/2/3 are cross-config comparison tests (surrogate vs high-fidelity,
+    # freeze vs non-freeze) with custom sed-normalized diffs of per-LP *stdout* --
+    # not determinism tests -- so they stay as scripts (same bucket as mapping_test).
+    # TODO: convert these to the planned lp-io normalize-and-sort comparison
+    # helper once it lands (the roadmap's canonical per-LP comparison; stdout
+    # scraping is explicitly the approach it replaces). Requires the surrogate path
+    # to emit lp-io output first.
+    # NB: their final packet-count check is a no-op (it execs the *.txt files
+    # instead of listing them); fixing that is deferred to its own commit.
     example-ping-pong-surrogate-1.sh
     example-ping-pong-surrogate-2.sh
     example-ping-pong-surrogate-3.sh
-    example-ping-pong-no-logging.sh
-    example-ping-pong-surrogate-determinism-1.sh
-    example-ping-pong-surrogate-determinism-2.sh
     )
 
 configure_file(conf/union-milc-jacobi-workload/dfdally-72-par.conf.in conf/union-milc-jacobi-workload/dfdally-72-par.conf.in @ONLY)
@@ -197,6 +240,36 @@ codes_add_equivalence_test(
     ARGS   --sync=3 --num_messages=10 --payload_sz=8192
     CONFIG doc/example/tutorial-ping-pong.conf)
 
+# Surrogate-mode determinism: same surrogate config run twice (np 3, sync=3),
+# committed-event counts must match. The two variants differ only in network
+# treatment. REQUIRE asserts the surrogate actually switched.
+codes_add_equivalence_test(
+    NAME    example-ping-pong-surrogate-determinism-no-freeze
+    BINARY  tutorial-synthetic-ping-pong
+    NP      3
+    ARGS    --sync=3 --num_messages=100 --payload_sz=8192
+    CONFIG  tutorial-ping-pong-surrogate.conf
+    SETUP   surrogate-determinism-no-freeze-setup.sh
+    REQUIRE "Network switch completed")
+codes_add_equivalence_test(
+    NAME    example-ping-pong-surrogate-determinism-freeze
+    BINARY  tutorial-synthetic-ping-pong
+    NP      3
+    ARGS    --sync=3 --num_messages=100 --payload_sz=8192
+    CONFIG  tutorial-ping-pong-surrogate.conf
+    SETUP   surrogate-determinism-freeze-setup.sh
+    REQUIRE "Network switch completed")
+
+# Smoke test: the sim runs cleanly with an empty packet-latency trace path.
+# Single run (SETUP generates the config; MARKER asserts it produced output).
+codes_add_run_test(
+    NAME   example-ping-pong-no-logging
+    BINARY tutorial-synthetic-ping-pong
+    NP     1
+    ARGS   --sync=1 --num_messages=10 --payload_sz=4096 -- tutorial-ping-pong.conf
+    SETUP  no-logging-setup.sh
+    MARKER "Net Events Processed")
+
 # Single-run smoke / unit tests (migrated from per-scenario shell scripts).
 # Config files live in the source tree; _tconf/_nwconf point at the two homes.
 set(_tconf "${CMAKE_CURRENT_SOURCE_DIR}/conf")
diff --git a/tests/equivalence-run.sh b/tests/equivalence-run.sh
index 297f9efc..30666756 100755
--- a/tests/equivalence-run.sh
+++ b/tests/equivalence-run.sh
@@ -1,45 +1,50 @@
 #!/bin/bash
 #
-# Generic equivalence runner for CODES tests.
+# Generic staged runner for CODES tests.
 #
-# Runs two (or more) commands, greps a marker line from each run's stdout, and
-# asserts the marked lines are identical across every run. Used for both:
-#   - reproducibility  (same command run N times -> result must not vary), and
-#   - seq-vs-optimistic (same args, differing --sync -> committed work must match).
+# Runs one or more commands, each in its own run-N/ subdir, and applies a set of
+# checks. Drives both single-run smoke tests and multi-run equivalence tests:
+#   - reproducibility   (same command run N times -> result must not vary),
+#   - seq-vs-optimistic  (same args, differing --sync -> committed work matches),
+#   - single-run smoke   (one run; pass on clean exit + marker present).
 #
-# It is driven entirely from CMake by codes_add_equivalence_test(); it is not
-# meant to be hand-edited per test. Each run executes in its own run-N/ subdir
-# so that runs writing to fixed relative output paths don't collide.
+# It is driven from CMake by codes_add_run_test() / codes_add_equivalence_test();
+# it is not meant to be hand-edited per test.
 #
 # Usage:
-#   equivalence-run.sh --marker "Net Events Processed" [--setup <script>] \
-#       @@ <cmd for run 1...> @@ <cmd for run 2...> [ @@ <run 3...> ]
+#   equivalence-run.sh [--marker <line>] [--require <line>]... [--setup <script>] \
+#       @@ <cmd for run 1...> [ @@ <cmd for run 2...> ... ]
 #
-# '@@' separates runs. A run's own '--' (ROSS opts | .conf) stays intact within
-# its segment. --setup names a script that is *sourced* before any run, so it
-# may export environment variables and/or generate config files in the sandbox.
+# '@@' separates runs; a run's own '--' (ROSS opts | .conf) stays intact within
+# its segment. Each run executes in run-N/ so runs writing to fixed relative
+# output paths don't collide. --setup names a script that is *sourced inside each
+# run's subdir* before that run, so it may export environment variables and/or
+# generate config files local to the run (referenced by bare name in the cmd).
+#
+# Checks:
+#   --marker <line>   the line must appear in every run's output; and, when there
+#                     are 2+ runs, the marker lines are diffed across runs (they
+#                     must be identical). Omit to skip the marker check/diff.
+#   --require <line>  the line must appear in every run's output (presence only,
+#                     never diffed). May be given multiple times.
 
 set -u
 
-marker="Net Events Processed"
+marker=""
 setup=""
+requires=()
 
 # Leading options, up to the first run separator.
 while [[ $# -gt 0 && "$1" != "@@" ]]; do
     case "$1" in
-        --marker) marker="$2"; shift 2 ;;
-        --setup)  setup="$2";  shift 2 ;;
+        --marker)  marker="$2";        shift 2 ;;
+        --require) requires+=("$2");    shift 2 ;;
+        --setup)   setup="$2";          shift 2 ;;
         *) echo "equivalence-run.sh: unknown option '$1'" >&2; exit 2 ;;
     esac
 done
 [[ "${1:-}" == "@@" ]] && shift
 
-# Sourced (not executed) so exported vars and generated confs are visible to runs.
-if [[ -n "$setup" ]]; then
-    # shellcheck disable=SC1090
-    source "$setup"
-fi
-
 run_idx=0
 cmd=()
 outputs=()
@@ -52,18 +57,35 @@ run_one() {
     local errf="${dir}/model-output-error.txt"
 
     echo "+ run ${run_idx}: ${cmd[*]}" >&2
-    ( cd "$dir" && "${cmd[@]}" ) > "$out" 2> "$errf"
+    # setup is sourced *inside* the run dir so generated confs / trace output are
+    # local to this run (isolating otherwise-colliding fixed relative paths).
+    (
+        cd "$dir" || exit 1
+        if [[ -n "$setup" ]]; then
+            # shellcheck disable=SC1090
+            source "$setup"
+        fi
+        "${cmd[@]}"
+    ) > "$out" 2> "$errf"
     local rc=$?
     if [[ $rc -ne 0 ]]; then
         echo "equivalence-run.sh: run ${run_idx} exited with $rc" >&2
         cat "$errf" >&2
         exit $rc
     fi
-    if ! grep -q "$marker" "$out"; then
+    if [[ -n "$marker" ]] && ! grep -q "$marker" "$out"; then
         echo "equivalence-run.sh: run ${run_idx} produced no '$marker' line" \
              "(did the simulation produce output?)" >&2
         exit 1
     fi
+    local req
+    for req in "${requires[@]:-}"; do
+        [[ -z "$req" ]] && continue
+        if ! grep -q "$req" "$out"; then
+            echo "equivalence-run.sh: run ${run_idx} missing required line '$req'" >&2
+            exit 1
+        fi
+    done
     outputs+=("$out")
     cmd=()
 }
@@ -77,12 +99,12 @@ for tok in "$@"; do
 done
 [[ ${#cmd[@]} -gt 0 ]] && run_one
 
-if [[ ${#outputs[@]} -lt 2 ]]; then
-    echo "equivalence-run.sh: need at least 2 runs to compare, got ${#outputs[@]}" >&2
-    exit 2
+# Cross-run comparison only applies with a marker and 2+ runs; a single run is a
+# smoke test whose checks already ran above.
+if [[ -z "$marker" || ${#outputs[@]} -lt 2 ]]; then
+    exit 0
 fi
 
-# Compare every run's marker line against the first.
 ref="${outputs[0]}"
 status=0
 for out in "${outputs[@]:1}"; do
diff --git a/tests/example-ping-pong-no-logging.sh b/tests/example-ping-pong-no-logging.sh
deleted file mode 100755
index 0fb0be8d..00000000
--- a/tests/example-ping-pong-no-logging.sh
+++ /dev/null
@@ -1,25 +0,0 @@
-#!/bin/bash
-# Test: checking simulation runs without any problem when "packet latency path" is not given
-
-if [[ -z $bindir ]] ; then
-    echo bindir variable not set
-    exit 1
-fi
-
-# Configuring surrogate instance
-export PACKET_SIZE=4096
-export CHUNK_SIZE=4096
-export PACKET_LATENCY_TRACE_PATH=
-cat "$bindir/doc/example"/tutorial-ping-pong.template.conf.in | envsubst > tutorial-ping-pong.conf
-
-# Running simulation twice with the same parameters
-
-mpirun -np 1 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=1 \
-    --num_messages=10 --payload_sz=4096 \
-    -- tutorial-ping-pong.conf \
-    > model-output-1.txt 2> model-output-1-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that there is actual output
-grep 'Net Events Processed' model-output-1.txt
diff --git a/tests/example-ping-pong-surrogate-determinism-1.sh b/tests/example-ping-pong-surrogate-determinism-1.sh
deleted file mode 100755
index 5726aa0b..00000000
--- a/tests/example-ping-pong-surrogate-determinism-1.sh
+++ /dev/null
@@ -1,57 +0,0 @@
-#!/bin/bash
-
-if [[ -z $bindir ]] ; then
-    echo bindir variable not set
-    exit 1
-fi
-
-# Configuring surrogate instance
-export PACKET_SIZE=1024
-export CHUNK_SIZE=1024
-export NETWORK_TREATMENT=nothing
-export PREDICTOR_TYPE=average
-export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate-1/
-export IGNORE_UNTIL=0.0
-export SWITCH_TIMESTAMPS='".08e6", ".1e6", ".2e6", ".6e6", ".7e6", ".9e6", "1.0e6", "1.3e6", "1.6e6", "1.7e6", "1.9e6", "2.0e6", "2.3e6", "2.6e6", "2.7e6", "2.9e6", "3.0e6", "3.3e6", "3.6e6", "3.7e6", "3.9e6", "4.0e6", "4.3e6", "4.6e6", "4.7e6", "4.9e6", "5.0e6", "9.8e6"'
-cat "$bindir/doc/example"/tutorial-ping-pong-surrogate.template.conf.in | envsubst > tutorial-ping-pong-surrogate-1.conf
-
-export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate-2/
-cat "$bindir/doc/example"/tutorial-ping-pong-surrogate.template.conf.in | envsubst > tutorial-ping-pong-surrogate-2.conf
-
-# Running simulation twice with the same parameters
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=100 --payload_sz=8192 \
-    -- tutorial-ping-pong-surrogate-1.conf \
-    > model-output-1.txt 2> model-output-1-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=100 --payload_sz=8192 \
-    -- tutorial-ping-pong-surrogate-2.conf \
-    > model-output-2.txt 2> model-output-2-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that there is actual output
-grep 'Net Events Processed' model-output-1.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that the surrogate switched properly
-grep 'Network switch completed' model-output-1.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# This checks for the number of events processed. If they are different, then
-# the simulation is not deterministic (so this should fail!). As always, just
-# a unit test
-diff <(grep 'Net Events Processed' model-output-1.txt) \
-    <(grep 'Net Events Processed' model-output-2.txt)
-err=$?
-if [[ $err -ne 0 ]]; then
-    >&2 echo "The number of net events processed does not coincide, ie," \
-        "the simulation is not deterministic"
-    exit $err
-fi
diff --git a/tests/example-ping-pong-surrogate-determinism-2.sh b/tests/example-ping-pong-surrogate-determinism-2.sh
deleted file mode 100755
index f7908a27..00000000
--- a/tests/example-ping-pong-surrogate-determinism-2.sh
+++ /dev/null
@@ -1,57 +0,0 @@
-#!/bin/bash
-
-if [[ -z $bindir ]] ; then
-    echo bindir variable not set
-    exit 1
-fi
-
-# Configuring surrogate instance
-export PACKET_SIZE=1024
-export CHUNK_SIZE=1024
-export NETWORK_TREATMENT=freeze
-export PREDICTOR_TYPE=average
-export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate-1/
-export IGNORE_UNTIL=0.0
-export SWITCH_TIMESTAMPS='".08e6", ".1e6", ".2e6", ".6e6", ".7e6", ".9e6", "1.0e6", "1.3e6", "1.6e6", "1.7e6", "1.9e6", "2.0e6", "2.3e6", "2.6e6", "2.7e6", "2.9e6", "3.0e6", "3.3e6", "3.6e6", "3.7e6", "3.9e6", "4.0e6", "4.3e6", "4.6e6", "4.7e6", "4.9e6", "5.0e6", "9.8e6"'
-cat "$bindir/doc/example"/tutorial-ping-pong-surrogate.template.conf.in | envsubst > tutorial-ping-pong-surrogate-1.conf
-
-export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate-2/
-cat "$bindir/doc/example"/tutorial-ping-pong-surrogate.template.conf.in | envsubst > tutorial-ping-pong-surrogate-2.conf
-
-# Running simulation twice with the same parameters
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=100 --payload_sz=8192 \
-    -- tutorial-ping-pong-surrogate-1.conf \
-    > model-output-1.txt 2> model-output-1-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-mpirun -np 3 "$bindir/doc/example/tutorial-synthetic-ping-pong" --sync=3 \
-    --num_messages=100 --payload_sz=8192 \
-    -- tutorial-ping-pong-surrogate-2.conf \
-    > model-output-2.txt 2> model-output-2-error.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that there is actual output
-grep 'Net Events Processed' model-output-1.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# Checking that the surrogate switched properly
-grep 'Network switch completed' model-output-1.txt
-err=$?
-[[ $err -ne 0 ]] && exit $err
-
-# This checks for the number of events processed. If they are different, then
-# the simulation is not deterministic (so this should fail!). As always, just
-# a unit test
-diff <(grep 'Net Events Processed' model-output-1.txt) \
-    <(grep 'Net Events Processed' model-output-2.txt)
-err=$?
-if [[ $err -ne 0 ]]; then
-    >&2 echo "The number of net events processed does not coincide, ie," \
-        "the simulation is not deterministic"
-    exit $err
-fi
diff --git a/tests/no-logging-setup.sh b/tests/no-logging-setup.sh
new file mode 100644
index 00000000..01001c99
--- /dev/null
+++ b/tests/no-logging-setup.sh
@@ -0,0 +1,9 @@
+# Sourced (not executed) by equivalence-run.sh inside the run dir.
+#
+# Generates the high-fidelity ping-pong config with an EMPTY packet-latency
+# trace path, so example-ping-pong-no-logging can verify the model runs cleanly
+# when that path is not given. $bindir is exported by run-test.sh.
+export PACKET_SIZE=4096
+export CHUNK_SIZE=4096
+export PACKET_LATENCY_TRACE_PATH=
+cat "$bindir/doc/example/tutorial-ping-pong.template.conf.in" | envsubst > tutorial-ping-pong.conf
diff --git a/tests/surrogate-determinism-freeze-setup.sh b/tests/surrogate-determinism-freeze-setup.sh
new file mode 100644
index 00000000..5efb98d1
--- /dev/null
+++ b/tests/surrogate-determinism-freeze-setup.sh
@@ -0,0 +1,15 @@
+# Sourced (not executed) by equivalence-run.sh inside each run dir.
+#
+# Generates the surrogate ping-pong config WITH network freezing
+# (NETWORK_TREATMENT=freeze) for example-ping-pong-surrogate-determinism-freeze.
+# A single PACKET_LATENCY_TRACE_PATH is fine because each run executes in its own
+# subdir, so the two runs' trace output cannot collide. $bindir is exported by
+# run-test.sh.
+export PACKET_SIZE=1024
+export CHUNK_SIZE=1024
+export NETWORK_TREATMENT=freeze
+export PREDICTOR_TYPE=average
+export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate/
+export IGNORE_UNTIL=0.0
+export SWITCH_TIMESTAMPS='".08e6", ".1e6", ".2e6", ".6e6", ".7e6", ".9e6", "1.0e6", "1.3e6", "1.6e6", "1.7e6", "1.9e6", "2.0e6", "2.3e6", "2.6e6", "2.7e6", "2.9e6", "3.0e6", "3.3e6", "3.6e6", "3.7e6", "3.9e6", "4.0e6", "4.3e6", "4.6e6", "4.7e6", "4.9e6", "5.0e6", "9.8e6"'
+cat "$bindir/doc/example/tutorial-ping-pong-surrogate.template.conf.in" | envsubst > tutorial-ping-pong-surrogate.conf
diff --git a/tests/surrogate-determinism-no-freeze-setup.sh b/tests/surrogate-determinism-no-freeze-setup.sh
new file mode 100644
index 00000000..5eeb59f6
--- /dev/null
+++ b/tests/surrogate-determinism-no-freeze-setup.sh
@@ -0,0 +1,15 @@
+# Sourced (not executed) by equivalence-run.sh inside each run dir.
+#
+# Generates the surrogate ping-pong config with NO network freezing
+# (NETWORK_TREATMENT=nothing) for example-ping-pong-surrogate-determinism-no-freeze.
+# A single PACKET_LATENCY_TRACE_PATH is fine because each run executes in its own
+# subdir, so the two runs' trace output cannot collide. $bindir is exported by
+# run-test.sh.
+export PACKET_SIZE=1024
+export CHUNK_SIZE=1024
+export NETWORK_TREATMENT=nothing
+export PREDICTOR_TYPE=average
+export PACKET_LATENCY_TRACE_PATH=packet-latency-surrogate/
+export IGNORE_UNTIL=0.0
+export SWITCH_TIMESTAMPS='".08e6", ".1e6", ".2e6", ".6e6", ".7e6", ".9e6", "1.0e6", "1.3e6", "1.6e6", "1.7e6", "1.9e6", "2.0e6", "2.3e6", "2.6e6", "2.7e6", "2.9e6", "3.0e6", "3.3e6", "3.6e6", "3.7e6", "3.9e6", "4.0e6", "4.3e6", "4.6e6", "4.7e6", "4.9e6", "5.0e6", "9.8e6"'
+cat "$bindir/doc/example/tutorial-ping-pong-surrogate.template.conf.in" | envsubst > tutorial-ping-pong-surrogate.conf

From d64824231d3521485c357a8e027860566675793e Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Tue, 30 Jun 2026 02:41:21 -0500
Subject: [PATCH 4/7] ci: correct misleading comment

---
 .github/workflows/build.yml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 9f6245fd..16c9240e 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -462,9 +462,10 @@ jobs:
 
       - name: Run CODES tests
         working-directory: codes
-        # The `full-ci` test preset excludes the union-surrogate director tests:
-        # their *.sh harnesses set only ~8 of the ~20 config-template vars
-        # (DIRECTOR_* etc.) so these tests fail.
+        # Runs the whole suite, including the union-surrogate tests. (These used
+        # to fail because their config template rendered an empty `dir-nw-lp` from
+        # unset DIRECTOR_* vars; the ML-director config was split out of the test
+        # config so the surrogate tests no longer pull it in.)
         run: ctest --preset full-ci
 
       - name: Upload logs on failure

From 14baa0aff624881b2234a0e2e8dc09599e4518ec Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Tue, 30 Jun 2026 16:31:40 -0500
Subject: [PATCH 5/7] tests: fix dead packet-count check in ping-pong surrogate
 tests

The final check globbed `packet-latency-*/*.txt | wc -l` with no command,
so bash tried to execute the trace files, wc counted 0 on both sides, and
the diff always passed. Add `cat` so it actually compares packet counts.
---
 tests/CMakeLists.txt                   | 2 --
 tests/example-ping-pong-surrogate-1.sh | 2 +-
 tests/example-ping-pong-surrogate-2.sh | 2 +-
 tests/example-ping-pong-surrogate-3.sh | 2 +-
 4 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index ada50ce0..0f864b85 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -203,8 +203,6 @@ set(test-shell-files
     # helper once it lands (the roadmap's canonical per-LP comparison; stdout
     # scraping is explicitly the approach it replaces). Requires the surrogate path
     # to emit lp-io output first.
-    # NB: their final packet-count check is a no-op (it execs the *.txt files
-    # instead of listing them); fixing that is deferred to its own commit.
     example-ping-pong-surrogate-1.sh
     example-ping-pong-surrogate-2.sh
     example-ping-pong-surrogate-3.sh
diff --git a/tests/example-ping-pong-surrogate-1.sh b/tests/example-ping-pong-surrogate-1.sh
index 6b9e4b8b..23575539 100755
--- a/tests/example-ping-pong-surrogate-1.sh
+++ b/tests/example-ping-pong-surrogate-1.sh
@@ -59,7 +59,7 @@ if [[ $err -ne 0 ]]; then
 fi
 
 # This checks for an equal number of packets transmitted
-diff <(packet-latency-surrogate/*.txt | wc -l) <(packet-latency-highdef/*.txt | wc -l)
+diff <(cat packet-latency-surrogate/*.txt | wc -l) <(cat packet-latency-highdef/*.txt | wc -l)
 err=$?
 if [[ $err -ne 0 ]]; then
     >&2 echo "The surrogate gave different results from high-fidelity on the number of packets transmitted"
diff --git a/tests/example-ping-pong-surrogate-2.sh b/tests/example-ping-pong-surrogate-2.sh
index a37d309a..9ea842bf 100755
--- a/tests/example-ping-pong-surrogate-2.sh
+++ b/tests/example-ping-pong-surrogate-2.sh
@@ -59,7 +59,7 @@ if [[ $err -ne 0 ]]; then
 fi
 
 # This checks for an equal number of packets transmitted
-diff <(packet-latency-surrogate/*.txt | wc -l) <(packet-latency-highdef/*.txt | wc -l)
+diff <(cat packet-latency-surrogate/*.txt | wc -l) <(cat packet-latency-highdef/*.txt | wc -l)
 err=$?
 if [[ $err -ne 0 ]]; then
     >&2 echo "The surrogate gave different results from high-fidelity on the number of packets transmitted"
diff --git a/tests/example-ping-pong-surrogate-3.sh b/tests/example-ping-pong-surrogate-3.sh
index ca04c245..1a3818f9 100755
--- a/tests/example-ping-pong-surrogate-3.sh
+++ b/tests/example-ping-pong-surrogate-3.sh
@@ -60,7 +60,7 @@ if [[ $err -ne 0 ]]; then
 fi
 
 # This checks for an equal number of packets transmitted
-diff <(packet-latency-freeze/*.txt | wc -l) <(packet-latency-non-freeze/*.txt | wc -l)
+diff <(cat packet-latency-freeze/*.txt | wc -l) <(cat packet-latency-non-freeze/*.txt | wc -l)
 err=$?
 if [[ $err -ne 0 ]]; then
     >&2 echo "The two modes (freezing and not) are processing a different number of packets"

From 8a6c13f96e1c13421bf23024acf7c5e40e17ec16 Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Tue, 30 Jun 2026 17:37:06 -0500
Subject: [PATCH 6/7] tests: add lp-io config-equivalence harness

codes_add_lpio_equivalence_test() runs a model with two configs (each with its
own --lp-io-dir) and diffs the per-LP lp-io output -- the identifier-file set
plus a sorted diff of each file. Two configs are equivalent iff every run
produces identical lp-io output. equivalence-run.sh gains a --lp-io comparison
mode to back it.

This is the safety net for swapping a legacy .conf for an equivalent new config
(e.g. a compiled YAML) and proving the simulation is byte-identical per LP.
Includes a synthetic-dragonfly proof-of-concept (same config twice) that also
serves as an lp-io determinism check.
---
 tests/CMakeLists.txt     | 59 +++++++++++++++++++++++++++++++++---
 tests/equivalence-run.sh | 64 +++++++++++++++++++++++++++++++++-------
 2 files changed, 108 insertions(+), 15 deletions(-)

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 0f864b85..dac82405 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -138,6 +138,46 @@ function(codes_add_run_test)
     endif()
 endfunction()
 
+# codes_add_lpio_equivalence_test — assert two configs produce equivalent results.
+#
+# Runs BINARY once per config (each with its own --lp-io-dir) and diffs the
+# resulting per-LP lp-io output -- the set of identifier files, and a sorted diff
+# of each. Two configs are equivalent iff every run produces identical lp-io. The
+# primary use is checking a new YAML config against the legacy .conf it replaces;
+# CONFIG_A/CONFIG_B can be any two config files the model accepts (format-agnostic,
+# so it works with .conf-vs-.conf today and .conf-vs-.yaml once the YAML adapter
+# lands). BINARY must be a model that emits lp-io (e.g. model-net-synthetic).
+#
+#   codes_add_lpio_equivalence_test(
+#       NAME     <ctest name>
+#       BINARY   <CMake target>
+#       CONFIG_A <path>                  # e.g. legacy .conf
+#       CONFIG_B <path>                  # e.g. new .yaml (or a second .conf)
+#       [NP      <ranks>]                # default 1
+#       [ARGS    <args shared by both runs, placed before the config>]
+#   )
+function(codes_add_lpio_equivalence_test)
+    cmake_parse_arguments(T "" "NAME;BINARY;NP;CONFIG_A;CONFIG_B" "ARGS" ${ARGN})
+    if(NOT T_NAME OR NOT T_BINARY OR NOT T_CONFIG_A OR NOT T_CONFIG_B)
+        message(FATAL_ERROR "codes_add_lpio_equivalence_test: NAME, BINARY, CONFIG_A and CONFIG_B are required")
+    endif()
+    if(NOT T_NP)
+        set(T_NP 1)
+    endif()
+    set(_bin    "$<TARGET_FILE:${T_BINARY}>")
+    set(_launch ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${T_NP} ${MPIEXEC_PREFLAGS})
+    # Each run writes lp-io into a fresh "lp-io" dir inside its own run-N subdir
+    # (lp_io_prepare mkdir's it and aborts if it already exists, so it must be
+    # relative + per-run-isolated, which the runner's subdirs provide).
+    add_test(NAME ${T_NAME}
+        COMMAND "${CMAKE_CURRENT_BINARY_DIR}/run-test.sh"
+                bash "${CMAKE_CURRENT_SOURCE_DIR}/equivalence-run.sh"
+                --marker "Net Events Processed" --lp-io lp-io
+                @@ ${_launch} "${_bin}" ${T_ARGS} --lp-io-dir=lp-io ${MPIEXEC_POSTFLAGS} -- "${T_CONFIG_A}"
+                @@ ${_launch} "${_bin}" ${T_ARGS} --lp-io-dir=lp-io ${MPIEXEC_POSTFLAGS} -- "${T_CONFIG_B}"
+        WORKING_DIRECTORY "${CODES_BINARY_DIR}")
+endfunction()
+
 # Unfortunatelly, CMake doesn't support iteration of a key-pair structure,
 # otherwise the following lists could be easily compressed into a single
 # list/dictionary/structure. Instead each C file name **MUST** match each
@@ -199,10 +239,9 @@ set(test-shell-files
     # surrogate-1/2/3 are cross-config comparison tests (surrogate vs high-fidelity,
     # freeze vs non-freeze) with custom sed-normalized diffs of per-LP *stdout* --
     # not determinism tests -- so they stay as scripts (same bucket as mapping_test).
-    # TODO: convert these to the planned lp-io normalize-and-sort comparison
-    # helper once it lands (the roadmap's canonical per-LP comparison; stdout
-    # scraping is explicitly the approach it replaces). Requires the surrogate path
-    # to emit lp-io output first.
+    # TODO: convert these to codes_add_lpio_equivalence_test (the canonical per-LP
+    # comparison; stdout scraping is the approach it replaces) once the surrogate
+    # path emits lp-io output.
     example-ping-pong-surrogate-1.sh
     example-ping-pong-surrogate-2.sh
     example-ping-pong-surrogate-3.sh
@@ -308,3 +347,15 @@ codes_add_run_test(NAME modelnet-test-fattree-synthetic BINARY model-net-synthet
     ARGS --sync=1 -- "${_nwconf}/modelnet-synthetic-fattree.conf")
 codes_add_run_test(NAME modelnet-test-slimfly-synthetic BINARY model-net-synthetic-slimfly
     ARGS --sync=1 -- "${_nwconf}/modelnet-synthetic-slimfly-min.conf")
+
+# Config-equivalence harness: run two configs, diff per-LP lp-io output.
+# Proof-of-concept uses the same config twice (must be identical -> also an lp-io
+# determinism check). When the YAML config adapter lands, CONFIG_B becomes the
+# compiled .yaml, giving the old-.conf vs new-.yaml equivalence check.
+codes_add_lpio_equivalence_test(
+    NAME     synthetic-dragonfly-lpio-equivalence
+    BINARY   model-net-synthetic
+    NP       1
+    ARGS     --sync=1 --num_messages=1
+    CONFIG_A "${_nwconf}/modelnet-synthetic-dragonfly.conf"
+    CONFIG_B "${_nwconf}/modelnet-synthetic-dragonfly.conf")
diff --git a/tests/equivalence-run.sh b/tests/equivalence-run.sh
index 30666756..082e6c35 100755
--- a/tests/equivalence-run.sh
+++ b/tests/equivalence-run.sh
@@ -13,7 +13,7 @@
 #
 # Usage:
 #   equivalence-run.sh [--marker <line>] [--require <line>]... [--setup <script>] \
-#       @@ <cmd for run 1...> [ @@ <cmd for run 2...> ... ]
+#       [--lp-io <dir>] @@ <cmd for run 1...> [ @@ <cmd for run 2...> ... ]
 #
 # '@@' separates runs; a run's own '--' (ROSS opts | .conf) stays intact within
 # its segment. Each run executes in run-N/ so runs writing to fixed relative
@@ -27,11 +27,16 @@
 #                     must be identical). Omit to skip the marker check/diff.
 #   --require <line>  the line must appear in every run's output (presence only,
 #                     never diffed). May be given multiple times.
+#   --lp-io <dir>     each run wrote per-LP output to run-N/<dir> (via the model's
+#                     --lp-io-dir); compare the identifier-file set and a sorted
+#                     diff of each file across runs. The per-LP config-equivalence
+#                     check (old .conf vs new .yaml). Needs 2+ runs.
 
 set -u
 
 marker=""
 setup=""
+lpio=""
 requires=()
 
 # Leading options, up to the first run separator.
@@ -40,6 +45,7 @@ while [[ $# -gt 0 && "$1" != "@@" ]]; do
         --marker)  marker="$2";        shift 2 ;;
         --require) requires+=("$2");    shift 2 ;;
         --setup)   setup="$2";          shift 2 ;;
+        --lp-io)   lpio="$2";           shift 2 ;;
         *) echo "equivalence-run.sh: unknown option '$1'" >&2; exit 2 ;;
     esac
 done
@@ -99,19 +105,55 @@ for tok in "$@"; do
 done
 [[ ${#cmd[@]} -gt 0 ]] && run_one
 
-# Cross-run comparison only applies with a marker and 2+ runs; a single run is a
-# smoke test whose checks already ran above.
-if [[ -z "$marker" || ${#outputs[@]} -lt 2 ]]; then
+# Cross-run comparisons need >= 2 runs; a single run is a smoke test whose
+# per-run checks already ran above.
+if [[ ${#outputs[@]} -lt 2 ]]; then
     exit 0
 fi
 
-ref="${outputs[0]}"
+n=${#outputs[@]}
 status=0
-for out in "${outputs[@]:1}"; do
-    if ! diff <(grep "$marker" "$ref") <(grep "$marker" "$out") >&2; then
-        echo "equivalence-run.sh: MISMATCH on '$marker' between ${ref} and ${out}" \
-             "-- the runs are not equivalent" >&2
-        status=1
+
+# Marker comparison: the marked line must be identical across all runs.
+if [[ -n "$marker" ]]; then
+    ref="${outputs[0]}"
+    for out in "${outputs[@]:1}"; do
+        if ! diff <(grep "$marker" "$ref") <(grep "$marker" "$out") >&2; then
+            echo "equivalence-run.sh: MISMATCH on '$marker' between ${ref} and ${out}" \
+                 "-- the runs are not equivalent" >&2
+            status=1
+        fi
+    done
+fi
+
+# lp-io comparison: each run wrote per-LP output to run-N/<lpio>. Compare the
+# set of identifier files and a *sorted* diff of each (per-LP line order is not
+# significant). Two equivalent configs produce identical lp-io output.
+if [[ -n "$lpio" ]]; then
+    refdir="run-1/$lpio"
+    if [[ ! -d "$refdir" ]]; then
+        echo "equivalence-run.sh: lp-io dir '$refdir' missing (did the run pass --lp-io-dir=$lpio?)" >&2
+        exit 1
     fi
-done
+    for ((i = 2; i <= n; i++)); do
+        d="run-${i}/$lpio"
+        if [[ ! -d "$d" ]]; then
+            echo "equivalence-run.sh: lp-io dir '$d' missing" >&2; status=1; continue
+        fi
+        if ! diff <(cd "$refdir" && ls | sort) <(cd "$d" && ls | sort) >&2; then
+            echo "equivalence-run.sh: lp-io identifier-file set differs (run-1 vs run-${i})" >&2
+            status=1; continue
+        fi
+        for f in "$refdir"/*; do
+            [[ -f "$f" ]] || continue
+            id=$(basename "$f")
+            if ! diff <(sort "$refdir/$id") <(sort "$d/$id") >&2; then
+                echo "equivalence-run.sh: lp-io MISMATCH on '$id' (run-1 vs run-${i})" \
+                     "-- the configs are not equivalent" >&2
+                status=1
+            fi
+        done
+    done
+fi
+
 exit $status

From 4c1241017494e5efc17c68526c86c32a7e304ca3 Mon Sep 17 00:00:00 2001
From: Caitlin Ross <caitlin.ross@kitware.com>
Date: Wed, 1 Jul 2026 13:08:29 -0500
Subject: [PATCH 7/7] ci: run the slow union-surrogate tests nightly, not on PR

The union-surrogate suite runs a heavy MILC+Jacobi UNION workload (~30 min for
the set) -- too long to gate every PR on. Label those tests "nightly" (plus a
per-test TIMEOUT) and have the full-lane job skip them on push/PR via
`ctest --label-exclude nightly`, running the complete set including them only
on the scheduled nightly build.
---
 .github/workflows/build.yml | 16 +++++++++++-----
 tests/CMakeLists.txt        | 11 ++++++++++-
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 16c9240e..ea04a6ae 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -462,11 +462,17 @@ jobs:
 
       - name: Run CODES tests
         working-directory: codes
-        # Runs the whole suite, including the union-surrogate tests. (These used
-        # to fail because their config template rendered an empty `dir-nw-lp` from
-        # unset DIRECTOR_* vars; the ML-director config was split out of the test
-        # config so the surrogate tests no longer pull it in.)
-        run: ctest --preset full-ci
+        # The union-surrogate tests (LABELS "nightly" in tests/CMakeLists.txt) run
+        # a heavy MILC+Jacobi UNION workload -- ~30 min for the set -- so PR/push
+        # skips them and the scheduled nightly build runs the full set including
+        # them. (Their director-free config fix means they no longer segfault on an
+        # empty dir-nw-lp; see tests/conf/union-milc-jacobi-workload/.)
+        run: |
+          if [ "${{ github.event_name }}" = "schedule" ]; then
+            ctest --preset full-ci
+          else
+            ctest --preset full-ci --label-exclude nightly
+          fi
 
       - name: Upload logs on failure
         if: failure()
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index dac82405..70ab98e5 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -250,7 +250,7 @@ set(test-shell-files
 configure_file(conf/union-milc-jacobi-workload/dfdally-72-par.conf.in conf/union-milc-jacobi-workload/dfdally-72-par.conf.in @ONLY)
 
 if(USE_UNION)
-    list(APPEND test-shell-files
+    set(union-shell-files
         union-workload-test-surrogate.sh
         union-workload-test-surrogate-smaller-chunk-size.sh
         union-workload-test-surrogate-parallel.sh
@@ -259,6 +259,7 @@ if(USE_UNION)
         union-workload-test-surrogate-parallel-deterministic-3.sh
         union-workload-test-surrogate-parallel-deterministic-4.sh
     )
+    list(APPEND test-shell-files ${union-shell-files})
 endif()
 
 foreach(testname ${test-shell-files})
@@ -267,6 +268,14 @@ foreach(testname ${test-shell-files})
         WORKING_DIRECTORY "${CODES_BINARY_DIR}")
 endforeach()
 
+# The union-surrogate tests run a heavy MILC+Jacobi UNION workload -- ~30 min for
+# the set. Label them "nightly" so PR/push CI skips them (ctest --label-exclude
+# nightly) and they run only on the scheduled nightly full-lane build, and give
+# each a generous timeout so a hang can't wedge that job.
+if(USE_UNION)
+    set_tests_properties(${union-shell-files} PROPERTIES LABELS "nightly" TIMEOUT 1200)
+endif()
+
 # Equivalence / determinism tests (replacing per-scenario shell scripts).
 # example-ping-pong-determinism.sh: run the optimistic sim twice, compare
 # committed-event counts (reproducibility).