feat(core): math + engine spike (split PR 1)

.githooks/commit-msg

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+FILE="${1:-}"
+if [[ -z "$FILE" || ! -f "$FILE" ]]; then
+  echo "[commit-msg] Missing commit message file. Usage: commit-msg <path>" >&2
+  exit 1
+fi
+
+SUBJECT=$(head -n1 "$FILE")
+if [[ -z "${SUBJECT// /}" ]]; then
+  echo "[commit-msg] Empty subject line is not allowed." >&2
+  exit 1
+fi
+
+# Discourage WIP commits (built-in regex; avoid spawning grep)
+if [[ "$SUBJECT" =~ ^[[:space:]]*[Ww][Ii][Pp]\b ]]; then
+  echo "[commit-msg] Please avoid 'WIP' in commit subjects. Tell a short story instead." >&2
+  exit 1
+fi
+
+# Soft length guidance (warn only)
+LEN=${#SUBJECT}
+if (( LEN > 72 )); then
+  echo "[commit-msg] Note: subject exceeds 72 chars ($LEN). Consider wrapping for readability." >&2
+fi
+
+exit 0

.githooks/pre-commit

@@ -1,53 +1,80 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Enforce coupling between PRNG algorithm/version and golden regression vector.
-
-PRNG_FILE="crates/rmg-core/src/math/prng.rs"
-
-# Only run if the PRNG file is staged
-if ! git diff --cached --name-only | grep -qx "$PRNG_FILE"; then
+if [[ "${SKIP_HOOKS:-}" == 1 ]]; then
   exit 0
 fi
 
-DIFF=$(git diff --cached -- "$PRNG_FILE" || true)
-
-# Heuristics to detect algorithm changes: edits to these functions imply behavior change
-if echo "$DIFF" | grep -E '^(\+|-)\s*(fn\s+next_u64|fn\s+from_seed_u64|fn\s+from_seed\(|fn\s+next_int\()' >/dev/null; then
-  ALGO_CHANGED=1
-else
-  ALGO_CHANGED=0
+# 1) PRNG coupling guard (existing logic)
+PRNG_FILE="crates/rmg-core/src/math/prng.rs"
+if git diff --cached --name-only | grep -qx "$PRNG_FILE"; then
+  DIFF=$(git diff --cached -- "$PRNG_FILE" || true)
+  if echo "$DIFF" | grep -E '^(\+|-)\s*(fn\s+next_u64|fn\s+from_seed_u64|fn\s+from_seed\(|fn\s+next_int\()' >/dev/null; then
+    ALGO_CHANGED=1
+  else
+    ALGO_CHANGED=0
+  fi
+  if echo "$DIFF" | grep -E 'PRNG_ALGO_VERSION' >/dev/null; then
+    VERSION_CHANGED=1
+  else
+    VERSION_CHANGED=0
+  fi
+  if echo "$DIFF" | grep -E 'next_int_golden_regression|assert_eq!\(values,\s*vec!\[' >/dev/null; then
+    GOLDEN_CHANGED=1
+  else
+    GOLDEN_CHANGED=0
+  fi
+  FAIL=0
+  if [[ "$ALGO_CHANGED" -eq 1 && "$VERSION_CHANGED" -eq 0 ]]; then
+    echo "pre-commit: PRNG algorithm changed but PRNG_ALGO_VERSION was not bumped." >&2
+    FAIL=1
+  fi
+  if [[ "$VERSION_CHANGED" -eq 1 && "$GOLDEN_CHANGED" -eq 0 ]]; then
+    echo "pre-commit: PRNG_ALGO_VERSION bumped but golden regression vector was not updated." >&2
+    FAIL=1
+  fi
+  if [[ "$FAIL" -eq 1 ]]; then
+    echo "pre-commit: Refusing commit. Update algorithm version and golden regression together." >&2
+    exit 1
+  fi
 fi
 
-# Version bump present?
-if echo "$DIFF" | grep -E 'PRNG_ALGO_VERSION' >/dev/null; then
-  VERSION_CHANGED=1
-else
-  VERSION_CHANGED=0
+# 2) Enforce toolchain pin (matches rust-toolchain.toml)
+if command -v rustup >/dev/null 2>&1; then
+  PINNED=$(awk -F '"' '/^channel/ {print $2}' rust-toolchain.toml 2>/dev/null || echo "")
+  ACTIVE=$(rustup show active-toolchain 2>/dev/null | awk '{print $1}')
+  if [[ -n "$PINNED" && "$ACTIVE" != "$PINNED"* ]]; then
+    echo "pre-commit: Active toolchain '$ACTIVE' != pinned '$PINNED'. Run: rustup override set $PINNED" >&2
+    exit 1
+  fi
 fi
 
-# Golden regression vector updated?
-if echo "$DIFF" | grep -E 'next_int_golden_regression|assert_eq!\(values,\s*vec!\[' >/dev/null; then
-  GOLDEN_CHANGED=1
-else
-  GOLDEN_CHANGED=0
-fi
+# 3) Format check (fast)
+cargo fmt --all -- --check
 
-FAIL=0
-if [[ "$ALGO_CHANGED" -eq 1 && "$VERSION_CHANGED" -eq 0 ]]; then
-  echo "pre-commit: PRNG algorithm changed but PRNG_ALGO_VERSION was not bumped." >&2
-  FAIL=1
+# 4) Docs guard (scaled): only require docs when core public API changed
+STAGED=$(git diff --cached --name-only)
+CORE_API_CHANGED=$(echo "$STAGED" | grep -E '^crates/rmg-core/src/.*\.rs$' | grep -v '/tests/' || true)
+if [[ -n "$CORE_API_CHANGED" ]]; then
+  echo "$STAGED" | grep -Fx 'docs/execution-plan.md' >/dev/null || { echo 'pre-commit: docs/execution-plan.md must be updated when core API changes.' >&2; exit 1; }
+  echo "$STAGED" | grep -Fx 'docs/decision-log.md' >/dev/null || { echo 'pre-commit: docs/decision-log.md must be updated when core API changes.' >&2; exit 1; }
 fi
 
-if [[ "$VERSION_CHANGED" -eq 1 && "$GOLDEN_CHANGED" -eq 0 ]]; then
-  echo "pre-commit: PRNG_ALGO_VERSION bumped but golden regression vector was not updated." >&2
-  FAIL=1
+# 5) Lockfile guard: ensure lockfile version is v3 (compatible with MSRV cargo)
+if [[ -f Cargo.lock ]]; then
+  VER_LINE=$(grep -n '^version = ' Cargo.lock | head -n1 | awk -F'= ' '{print $2}')
+  if [[ "$VER_LINE" != "3" && "$VER_LINE" != "3\r" ]]; then
+    echo "pre-commit: Cargo.lock must be generated with Cargo 1.68 (lockfile v3)." >&2
+    echo "Run: cargo +1.68.0 generate-lockfile" >&2
+    exit 1
+  fi
 fi
 
-if [[ "$FAIL" -eq 1 ]]; then
-  echo "pre-commit: Refusing commit. Update algorithm version and golden regression together." >&2
-  exit 1
-fi
+# 6) Targeted clippy + check for changed crates (fast-ish)
+CRATES=$(echo "$STAGED" | sed -n 's#^crates/\([^/]*\)/.*#\1#p' | sort -u)
+for c in $CRATES; do
+  cargo clippy -p "$c" --all-targets -- -D warnings -D missing_docs
+  cargo check -p "$c" --quiet
+done
 
 exit 0
-

.githooks/pre-push

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+PINNED="${PINNED:-1.68.0}"
+
+for cmd in cargo rustup rg; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "[pre-push] missing dependency: $cmd. Install it and retry." >&2
+    exit 1
+  fi
+done
+
+echo "🐰 BunBun 🐇"
+
+if [[ "${SKIP_HOOKS:-}" == 1 ]]; then
+  exit 0
+fi
+
+echo "[pre-push] fmt"
+cargo +"$PINNED" fmt --all -- --check
+
+echo "[pre-push] clippy (workspace)"
+cargo +"$PINNED" clippy --all-targets -- -D warnings -D missing_docs
+
+echo "[pre-push] tests (workspace)"
+cargo +"$PINNED" test --workspace
+
+# MSRV check for rmg-core
+echo "[pre-push] MSRV check (rmg-core @ $PINNED)"
+if rustup run "$PINNED" cargo -V >/dev/null 2>&1; then
+  cargo +"$PINNED" check -p rmg-core --all-targets
+else
+  echo "[pre-push] MSRV toolchain $PINNED not installed. Install via: rustup toolchain install $PINNED" >&2
+  exit 1
+fi
+
+# Rustdoc warnings guard (core API)
+echo "[pre-push] rustdoc warnings gate (rmg-core)"
+RUSTDOCFLAGS="-D warnings" cargo +"$PINNED" doc -p rmg-core --no-deps
+
+# Banned patterns
+echo "[pre-push] scanning banned patterns"
+# Match any crate-level allow(...) that includes missing_docs; exclude telemetry.rs explicitly
+if rg -n '#!\[allow\([^]]*missing_docs[^]]*\)\]' --glob '!crates/rmg-core/src/telemetry.rs' crates >/dev/null; then
+  echo "pre-push: crate-level allow(missing_docs) is forbidden (except telemetry.rs)." >&2
+  rg -n '#!\[allow\([^]]*missing_docs[^]]*\)\]' --glob '!crates/rmg-core/src/telemetry.rs' crates | cat >&2 || true
+  exit 1
+fi
+if rg -n "\#\[unsafe\(no_mangle\)\]" crates >/dev/null; then
+  echo "pre-push: #[unsafe(no_mangle)] is invalid; use #[no_mangle]." >&2
+  rg -n "\#\[unsafe\(no_mangle\)\]" crates | cat >&2 || true
+  exit 1
+fi
+
+exit 0

.githooks/pre-rebase

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+echo "[pre-rebase] Rebase is disallowed for this repository. Use merge instead." >&2
+exit 1
+

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ jobs:
         with:
           submodules: false
       - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: |
@@ -31,11 +32,18 @@ jobs:
         with:
           submodules: false
       - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          components: clippy
+      - name: rustup override stable
+        run: rustup toolchain install stable && rustup override set stable
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: |
             .
       - name: cargo clippy
+        env:
+          RUSTUP_TOOLCHAIN: stable
         run: cargo clippy --all-targets -- -D warnings -D missing_docs
 
   test:
@@ -46,11 +54,17 @@ jobs:
         with:
           submodules: false
       - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+      - name: rustup override stable
+        run: rustup toolchain install stable && rustup override set stable
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: |
             .
       - name: cargo test
+        env:
+          RUSTUP_TOOLCHAIN: stable
         run: cargo test
       - name: PRNG golden regression (rmg-core)
         run: cargo test -p rmg-core --features golden_prng -- tests::next_int_golden_regression
@@ -86,3 +100,36 @@ jobs:
             echo 'docs/decision-log.md must be updated when non-doc files change.';
             exit 1;
           }
+
+  msrv:
+    name: MSRV (rmg-core @ 1.68)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+      - uses: dtolnay/rust-toolchain@1.68.0
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: |
+            .
+      - name: cargo check (rmg-core)
+        run: cargo check -p rmg-core --all-targets
+
+  rustdoc:
+    name: Rustdoc (rmg-core warnings gate)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+      - name: rustup override stable
+        run: rustup toolchain install stable && rustup override set stable
+      - uses: Swatinem/rust-cache@v2
+      - name: rustdoc warnings gate
+        env:
+          RUSTUP_TOOLCHAIN: stable
+        run: RUSTDOCFLAGS="-D warnings" cargo doc -p rmg-core --no-deps