fix(#16): wire provisioned cmake lib root + link/run tests in the gate (review bounce)

Review findings addressed (PR #17 bounce):
1. gate.sh put the provisioned cmake/ninja on PATH but never added their
   OWN lib root to LD_LIBRARY_PATH, so cmake died with exit 127
   (librhash.so.0 / libuv.so.1 / libjsoncpp.so.25 not found) and cmake-rs
   misreported 'is cmake not installed?'. The LLVM_BIN2 block now exports
   LD_LIBRARY_PATH=~/local-tools/root/usr/lib/x86_64-linux-gnu (same
   append pattern as the other two roots; final value carries all three).
2. The gate was compile-only. It now runs three steps: cargo check
   --all-targets (type-check), cargo test --no-run (LINK every test
   binary), cargo test --lib (EXECUTE headless lib unit tests).
3. docs/build-gate.md: prerequisites list the provisioned cmake's
   shared-lib root, the test-execution decision record, and the new
   troubleshooting entry.

Verified on the review box: cold full gate exits 0 (GATE_OK), step 1
check then 11m52s test-link codegen then 'running 0 tests / ok' (main has
no #[test] fns yet; the inbound netplay PRs add ~38); warm re-run 5.6s.

docs/build-gate.md

@@ -5,12 +5,15 @@ The project's review gate is a single documented command — see
 
 ```sh
 ./scripts/gate.sh        # == git submodule update --init --recursive
-                         #    + cargo check --all-targets
+                         #    + cargo check --all-targets   (type-check)
+                         #    + cargo test --no-run         (link tests)
+                         #    + cargo test --lib            (run headless lib tests)
 ```
 
-It must exit 0 on a clean `origin/main` checkout before any PR is gated
-(issue #16: all open PRs were unverifiable because `main` itself did not
-build).
+It must exit 0 (`GATE_OK`) on a clean `origin/main` checkout before any PR
+is gated (issue #16: all open PRs were unverifiable because `main` itself
+did not build; review bounce: the gate previously also stopped at
+`cargo check` — compiled but never linked or ran tests).
 
 ## Why the defaults were changed (`.cargo/config.toml`)
 
@@ -53,6 +56,13 @@ user-local roots extracted from Ubuntu `.debs` are provisioned:
   (plus `cmake`, `ninja`, `pkgconf`, `wayland-scanner` in
   `~/local-tools/root/usr/bin`), `libclang-18.so` in
   `~/local-tools/root/usr/lib/llvm-18/lib`
+- `~/local-tools/root/usr/lib/x86_64-linux-gnu` — the shared-lib root of
+  the SAME provisioned tree as the `cmake`/`ninja` above. Those binaries
+  link against `librhash.so.0`, `libuv.so.1`, `libjsoncpp.so.25` from this
+  directory; without it on `LD_LIBRARY_PATH` cmake dies at exec time with
+  `error while loading shared libraries: librhash.so.0` (exit 127) and
+  `cmake-rs` misreports it as `is "cmake" not installed?`. `gate.sh` adds
+  this root (see the `LLVM_BIN2` block), exactly like the other two roots.
 - `~/.local/bin-fc/pkg-config` — wrapper that execs the real `pkgconf`
   (the pypi `pkg-config`/`pkgconf-pypi` shims on `~/.local/bin` wrongly
   report exit 0 for missing packages, which makes cmake enable optional
@@ -64,6 +74,30 @@ user-local roots extracted from Ubuntu `.debs` are provisioned:
 `scripts/gate.sh` wires all of these onto PATH/env when present; on hosts
 with system toolchains the provisioning blocks are no-ops.
 
+## What the gate runs, and why
+
+Three steps, so a failure is attributable to exactly one phase:
+
+1. `cargo check --all-targets` — type-checks every target including tests.
+   This is the historical blocker phase (#16: `num-traits` SIGABRT under
+   the old `target-cpu=x86-64-v3`).
+2. `cargo test --no-run` — LINKS every test binary. A test that
+   type-checks but cannot link is still a broken gate; `cargo check` alone
+   never proves linkability. This answers the review question "the gate
+   compiles the tests but never runs them" for the link half.
+3. `cargo test --lib` — EXECUTES the library unit tests (headless: the
+   netplay state-sync/rollback logic; no window or device needed). Test
+   execution was deliberately NOT assumed: this step is wired in because it
+   completes on the review box. `main` currently has 0 `#[test]` fns
+   (measured in the #16 review; the inbound netplay PRs add ~38), so a
+   clean run reports `0 passed` — the mechanism, not the coverage, is what
+   this gate guarantees until those PRs land.
+
+Decision record: `cargo test --no-run` and `cargo test --lib` were both
+verified to complete here; running the full `cargo test` (which would also
+run windowed/bin tests) was not wired because it needs an interactive
+display and the review box's gate must stay headless-deterministic.
+
 ## Troubleshooting
 
 - `memory allocation of 648518346341351440 bytes failed` (SIGABRT in a
@@ -80,3 +114,9 @@ with system toolchains the provisioning blocks are no-ops.
 - SDL cmake: `SDL could not find X11 or Wayland development libraries` —
   CMake's FindX11 needs `CMAKE_INCLUDE_PATH`/`CMAKE_LIBRARY_PATH` pointed
   at the X11 dev root (pkg-config alone is not consulted for X11).
+- `cmake: error while loading shared libraries: librhash.so.0` (exit 127),
+  reported by cmake-rs as `is "cmake" not installed?` — the provisioned
+  cmake/ninja need their OWN root
+  (`~/local-tools/root/usr/lib/x86_64-linux-gnu`) on `LD_LIBRARY_PATH`;
+  `gate.sh`'s `LLVM_BIN2` block does this. This was the issue #16 review
+  bounce.

scripts/gate.sh

@@ -14,7 +14,16 @@
 #          clang for `-flto=thin`)
 #        - a real pkgconf + fontconfig/X11 dev pc files (the box has no
 #          system pkg-config/fontconfig and no sudo)
-#   3. Runs `cargo check --all-targets`.
+#        - the provisioned cmake/ninja's OWN lib root on LD_LIBRARY_PATH
+#          (without it cmake dies with exit 127: librhash/libuv/libjsoncpp
+#          not found)
+#   3. Runs the gate, as three distinguishable steps:
+#        a. `cargo check --all-targets` — TYPE-check everything, tests
+#           included (compile-only; the historical main blocker)
+#        b. `cargo test --no-run`      — LINK every test binary (a test
+#           that type-checks but cannot link is still a broken gate)
+#        c. `cargo test --lib`         — EXECUTE the headless library unit
+#           tests (netplay state sync etc.; see docs/build-gate.md)
 #
 # On AVX2-capable hardware, opt into the optimised CPU target:
 #   RUSTFLAGS="-C target-cpu=x86-64-v3" ./scripts/gate.sh
@@ -38,6 +47,11 @@ if [ -d "$LLVM_BIN" ]; then
 fi
 if [ -d "$LLVM_BIN2" ]; then
     export PATH="$LLVM_BIN2:$PATH"         # cmake, ninja, pkgconf, wayland-scanner
+    # cmake/ninja from this root link against librhash/libuv/libjsoncpp that
+    # ship in the SAME root (`usr/lib/x86_64-linux-gnu`); without that dir on
+    # LD_LIBRARY_PATH they die with exit 127 and cmake-rs reports it as
+    # "is `cmake` not installed?" — the issue #16 review bounce.
+    export LD_LIBRARY_PATH="$HOME/local-tools/root/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
 fi
 if [ -x "$FCPC" ] && [ -d "$PC_DIR" ]; then
     export PATH="$(dirname "$FCPC"):$PATH" # real pkg-config (not the pypi shim)
@@ -53,4 +67,15 @@ if [ -d "$HOME/local-tools/root/usr/lib/llvm-18/lib" ]; then
     export LD_LIBRARY_PATH="$HOME/local-tools/root/usr/lib/llvm-18/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
 fi
 
-exec cargo check --all-targets
+# --- Gate: type-check, then link tests, then run the headless lib tests ----
+echo "GATE step 1/3: cargo check --all-targets"
+cargo check --all-targets
+
+echo "GATE step 2/3: cargo test --no-run"
+cargo test --no-run
+
+echo "GATE step 3/3: cargo test --lib"
+cargo test --lib
+
+echo "GATE_OK"
+