2 files changed, 123 insertions, 0 deletions
diff --git a/scripts/testing/lib/maint-scenario.sh b/scripts/testing/lib/maint-scenario.sh
new file mode 100644
index 0000000..e7fcdda
--- /dev/null
+++ b/scripts/testing/lib/maint-scenario.sh
@@ -0,0 +1,62 @@
+#!/bin/bash
+# Shared contract and execution helpers for maint scenario transports.
+
+# Extract one declared variable from a scenario file in a clean subshell.
+_scenario_var() {  # <file> <varname>
+    bash -c 'set -eu; source "$1" || exit 9; eval "printf %s \"\${$2-}\""' \
+        _probe "$1" "$2" 2>/dev/null
+}
+
+_validate_scenario() {  # <file> -> fatal on contract violation
+    local f="$1" base probe_err
+    base=$(basename "$f")
+    probe_err=$(bash -c 'set -eu; source "$1"
+        : "${SCENARIO_DESC:?missing SCENARIO_DESC}"
+        : "${SCENARIO_GROUP:?missing SCENARIO_GROUP}"
+        : "${SCENARIO_PROFILES:?missing SCENARIO_PROFILES}"
+        for p in $SCENARIO_PROFILES; do
+            case "$p" in btrfs|zfs|any) ;; *)
+                echo "bad profile token: $p" >&2; exit 1 ;;
+            esac
+        done
+        declare -f scenario_break scenario_fix scenario_assert >/dev/null \
+            || { echo "missing scenario_break/fix/assert" >&2; exit 1; }' \
+        _probe "$f" 2>&1 >/dev/null) \
+        || fatal "scenario contract violation in $base: $probe_err"
+}
+
+run_scenario() {  # <index>
+    local i="$1" name="${S_NAMES[$1]}" f="${S_FILES[$1]}"
+    section "Scenario: $name — ${S_DESCS[$1]}"
+    # shellcheck disable=SC1090
+    source "$f"
+    local ok=true
+    step "break"
+    if ! scenario_break; then
+        error "$name: break step failed"
+        ok=false
+    fi
+    if [ "$ok" = "true" ]; then
+        step "fix"
+        if ! scenario_fix; then
+            error "$name: fix step failed"
+            ok=false
+        fi
+    fi
+    if [ "$ok" = "true" ]; then
+        step "assert"
+        if ! scenario_assert; then
+            error "$name: post-state assertion failed"
+            ok=false
+        fi
+    fi
+    unset -f scenario_break scenario_fix scenario_assert
+    unset SCENARIO_DESC SCENARIO_GROUP SCENARIO_PROFILES
+    if [ "$ok" = "true" ]; then
+        success "PASS: $name"
+        PASS+=("$name")
+    else
+        error "FAIL: $name"
+        FAIL+=("$name")
+    fi
+}
diff --git a/scripts/testing/lib/run-common.sh b/scripts/testing/lib/run-common.sh
new file mode 100644
index 0000000..b5696db
--- /dev/null
+++ b/scripts/testing/lib/run-common.sh
@@ -0,0 +1,61 @@
+#!/bin/bash
+# Transport-independent polling and reporting for archsetup test runners.
+
+archsetup_process_running() {  # <transport-function>
+    local transport="$1"
+    "$transport" "pgrep -f '[b]ash archsetup' > /dev/null" 2>/dev/null
+}
+
+wait_for_archsetup() {  # <transport> <max-polls> <seconds> <progress-every> [callback]
+    local transport="$1" max_polls="$2" poll_seconds="$3"
+    local progress_every="$4" progress_callback="${5:-}"
+    ARCHSETUP_POLL_COUNT=0
+
+    while [ "$ARCHSETUP_POLL_COUNT" -lt "$max_polls" ]; do
+        archsetup_process_running "$transport" || return 0
+        sleep "$poll_seconds"
+        ARCHSETUP_POLL_COUNT=$((ARCHSETUP_POLL_COUNT + 1))
+        if [ "$progress_every" -gt 0 ] \
+           && [ $((ARCHSETUP_POLL_COUNT % progress_every)) -eq 0 ] \
+           && [ -n "$progress_callback" ]; then
+            "$progress_callback" "$ARCHSETUP_POLL_COUNT"
+        fi
+    done
+    return 124
+}
+
+write_archsetup_test_report() {
+    local file="$1" title="$2" test_id="$3" method="$4" context="$5"
+    local completed="$6" passed="$7" count_passed="$8" count_failed="$9"
+    shift 9
+    local count_warnings="$1" artifacts="$2" validation="FAILED"
+    [ "$passed" = "true" ] && validation="PASSED"
+
+    {
+        echo "========================================"
+        echo "$title"
+        echo "========================================"
+        echo
+        echo "Test ID: $test_id"
+        echo "Date: $(date +'%Y-%m-%d %H:%M:%S')"
+        echo "Test Method: $method"
+        if [ -n "$context" ]; then
+            echo
+            printf '%s\n' "$context"
+        fi
+        echo
+        echo "Results:"
+        echo "  ArchSetup Completed: $completed (completion marker, not the installer's exit code)"
+        echo "  Validation: $validation"
+        echo
+        echo "Validation Summary:"
+        echo "  Passed:   $count_passed"
+        echo "  Failed:   $count_failed"
+        echo "  Warnings: $count_warnings"
+        if [ -n "$artifacts" ]; then
+            echo
+            printf '%s\n' "$artifacts"
+        fi
+        echo
+    } > "$file"
+}