Add fuzz_test.sh: a long-running gdb-driven fuzz loop over cross_sectional_200k.ep_

Documents two build/invocation bugs hit getting this working: DEBUG builds
need MP=1 too or --cpus is silently unrecognized, and gdb's
"handle SIGTRAP nostop noprint pass" breaks thread control against the
MP/pthread binary (misdiagnosed at first as a sandboxed ptrace restriction,
but reproduces outside any harness and goes away once that directive is
dropped).

Co-Authored-By: Claude Sonnet 5 <[email protected]>

2 files changed, 118 insertions, 0 deletions

diff --git a/src/TESTING_PLAN.md b/src/TESTING_PLAN.md
index abf35e3..7d2bfc2 100644
--- a/src/TESTING_PLAN.md
+++ b/src/TESTING_PLAN.md
@@ -251,3 +251,48 @@ search, eval, or hash.
    adversarial/degenerate-position term-bounds checks.
 6. Round out perf testing per the list above, with stored baselines
    and pass/fail thresholds instead of print-only output.
+
+## "Fuzz" testing
+
+**Implemented: `fuzz_test.sh [binary] [depth] [batch_size] [cpus]`**
+(defaults: `./_typhoon`, `sd 6`, 200 positions/batch, `--cpus 2`). Loops
+forever: each iteration draws a fresh random batch of `setboard`/`go`
+records from the full 400,000-line / 200k-position
+`tests/cross_sectional_200k.ep_` pool, runs them through a `DEBUG=1`
+build under gdb, and scans the gdb output for a crash/assert signature
+before starting the next batch. Stops (exit 1) and prints the offending
+batch + engine log paths as soon as one is found; otherwise runs
+indefinitely (`^C` to stop). Logs land under `/usr/local/tmp/typhoon/fuzz/`
+(one sampled `.ep_` batch + one `.gdb.txt` + one engine `--logfile` per
+iteration).
+
+**Two build/invocation bugs found and fixed getting this working, neither
+a sandbox limitation despite first appearances:**
+
+1. **The DEBUG binary must be built with `MP=1` as well as `DEBUG=1`**
+   (`gmake clean; gmake DEBUG=1 MP=1`) -- `--cpus` is compiled in only
+   under `#ifdef MP` (`main.c:311`). A `DEBUG=1`-only build silently
+   treats `--cpus` and its numeric argument as two separate unrecognized
+   arguments (`main.c:400`'s "Error (unknown argument)" path) and falls
+   back to the 1-cpu default with no hard failure -- easy to miss, and it
+   also means `split.c`'s parallel-search code never actually links in,
+   defeating the point of passing `--cpus 2` at all.
+2. **`gdb -batch -ex "handle SIGTRAP nostop noprint pass" -ex run ...`
+   breaks thread control against this MP/pthread build specifically**,
+   producing `ptrace (PT_SUSPEND): Operation not permitted` followed by
+   `Child process unexpectedly missing: No child processes` -- looked
+   exactly like a sandboxed environment blocking ptrace outright (and was
+   initially misdiagnosed as that), but reproduced identically outside
+   any harness/sandbox, and disappeared entirely once that one `-ex` line
+   was dropped. `fuzz_test.sh` omits it; a plain `run`/`bt full`/
+   `info registers` gdb batch invocation debugs the MP binary fine,
+   including catching a genuine `int3` breakpoint from a failed `ASSERT`.
+
+Not yet done: no crash has been found by a run so far, so the
+crash-detection path (the `grep -qE` in `fuzz_test.sh`) is exercised by
+its own logic reading correctly, not yet by a real hit. Worth periodically
+running this for stretches (it's unbounded/`^C`-driven, unlike the other
+gates) rather than treating it as a one-time pass/fail check like
+`debug_smoke_test.sh`. See also: `./debug_smoke_test.sh` (fast, curated
+sample, single pass/fail) for the pre-commit-sized version of the same
+idea.
diff --git a/src/fuzz_test.sh b/src/fuzz_test.sh
new file mode 100755
index 0000000..5e3d5f7
--- /dev/null
+++ b/src/fuzz_test.sh
@@ -0,0 +1,73 @@
+#!/bin/sh
+# Long-running fuzz loop per TESTING_PLAN.md's "Fuzz testing" section:
+# repeatedly draw a fresh random batch of setboard/go records from the full
+# 200k-position tests/cross_sectional_200k.ep_ pool, run them through a
+# DEBUG=1 build under gdb (so any assert/SIGTRAP/SIGSEGV leaves a full
+# backtrace instead of just a bare crash), shallow-depth, small/no hash
+# (setboard memsets the hash table as a side effect, so a large --hash
+# wastes time on every single record), --cpus 2 to exercise split.c's
+# parallel search path too. Runs until stopped (^C) or a crash is found.
+#
+# Usage: ./fuzz_test.sh [binary] [depth] [batch_size] [cpus]
+
+BIN="${1:-./_typhoon}"
+DEPTH="${2:-6}"
+BATCH="${3:-200}"
+CPUS="${4:-2}"
+SUITE=../tests/cross_sectional_200k.ep_
+LOGDIR=/usr/local/tmp/typhoon/fuzz
+mkdir -p "$LOGDIR"
+
+if [ ! -x "$BIN" ]; then
+    echo "ERROR: $BIN not found/executable (build first: gmake clean; gmake DEBUG=1 MP=1)"
+    exit 1
+fi
+if [ ! -f "$SUITE" ]; then
+    echo "ERROR: $SUITE not found (run from src/)"
+    exit 1
+fi
+
+TOTAL_RECORDS=$(grep -c '^go' "$SUITE")
+
+ITER=0
+while :; do
+    ITER=$((ITER + 1))
+    SAMPLE="$LOGDIR/batch_${ITER}.ep_"
+    awk -v k="$BATCH" -v n="$TOTAL_RECORDS" 'BEGIN { srand() }
+        { sub(/\r$/, "") }
+        /^setboard/ { rec = $0; next }
+        /^go[ \t]*$/ { rec = rec "\n" $0; c++; recs[c] = rec; rec = ""; next }
+        rec != "" { rec = rec "\n" $0 }
+        END {
+            picked = 0
+            while (picked < k && picked < c) {
+                r = int(rand() * c) + 1
+                if (!(r in used)) { used[r] = 1; print recs[r]; picked++ }
+            }
+        }' "$SUITE" > "$SAMPLE"
+
+    STAMP=$(date +%Y%m%d_%H%M%S)
+    LOG="$LOGDIR/run_${ITER}_${STAMP}.log"
+    GDBOUT="$LOGDIR/run_${ITER}_${STAMP}.gdb.txt"
+
+    echo "=== iter $ITER: $BATCH positions from $SUITE (sd $DEPTH, cpus $CPUS) -> $GDBOUT ==="
+
+    gdb -q -batch \
+        -ex "set pagination off" \
+        -ex run \
+        -ex "bt full" \
+        -ex "info registers" \
+        --args "$BIN" --cpus "$CPUS" --hash 1m --logfile "$LOG" \
+            --batch --command "force; book name /nonexistent.book.bin; sd $DEPTH; script $SAMPLE" \
+        > "$GDBOUT" 2>&1
+    STATUS=$?
+
+    if grep -qE 'Program terminated with signal (SIGSEGV|SIGABRT|SIGBUS|SIGILL|SIGFPE)|Assertion failure' "$GDBOUT"; then
+        echo "*** CRASH/ASSERT DETECTED on iter $ITER -- see $GDBOUT ***"
+        echo "    positions: $SAMPLE"
+        echo "    engine log: $LOG"
+        exit 1
+    fi
+
+    echo "    iter $ITER clean (exit=$STATUS)"
+done