merge(train-geom-1): resolve docs + hook conflicts with origin/main

Author: flyingrobots

.devcontainer/devcontainer.json

@@ -0,0 +1,37 @@
+{
+  "name": "echo-dev",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "username": "vscode",
+      "installZsh": false
+    },
+    "ghcr.io/devcontainers/features/rust:1": {
+      "profile": "minimal",
+      "components": ["rustfmt", "clippy"]
+    },
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "rust-lang.rust-analyzer",
+        "serayuzgur.crates",
+        "tamasfe.even-better-toml",
+        "vadimcn.vscode-lldb"
+      ]
+    }
+  },
+  "mounts": [
+    "source=devcontainer-cargo-cache,target=/usr/local/cargo,type=volume",
+    "source=devcontainer-rustup-cache,target=/usr/local/rustup,type=volume"
+  ],
+  "containerEnv": {
+    "CARGO_TERM_COLOR": "always"
+  },
+  "overrideCommand": false,
+  "postCreateCommand": "/bin/bash .devcontainer/post-create.sh"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[devcontainer] Installing default toolchain (1.71.1 via rust-toolchain.toml)..."
+if ! command -v rustup >/dev/null 2>&1; then
+  curl --proto '=https' --tlsv1.2 --retry 10 --retry-connrefused --location --silent --show-error --fail https://sh.rustup.rs | sh -s -- --default-toolchain none -y
+  export PATH="$HOME/.cargo/bin:$PATH"
+fi
+
+rustup toolchain install 1.71.1 --profile minimal
+# Do not override default; let rust-toolchain.toml control selection for this repo.
+# Ensure components/targets are available for the default toolchain (1.71.1).
+rustup component add --toolchain 1.71.1 rustfmt clippy || true
+rustup target add --toolchain 1.71.1 wasm32-unknown-unknown || true
+
+echo "[devcontainer] Priming cargo registry cache (optional)..."
+cargo fetch || true
+
+echo "[devcontainer] Done. Run 'cargo test -p rmg-core' or 'make ci-local' to validate."

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,mdx}]
+trim_trailing_whitespace = false
+
+[*.{ts,tsx,js,json}]
+indent_size = 2
+

.githooks/commit-msg

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+
 if [[ "${SKIP_HOOKS:-}" == 1 ]]; then
   exit 0
 fi
@@ -49,8 +50,27 @@ if command -v rustup >/dev/null 2>&1; then
   fi
 fi
 
-# 3) Format check (fast)
-cargo fmt --all -- --check
+# 3) Format (auto-fix if opted in)
+_auto_fmt="${ECHO_AUTO_FMT:-1}"
+case "${_auto_fmt}" in
+  1|true|TRUE|yes|YES|on|ON)
+    echo "pre-commit: ECHO_AUTO_FMT=${_auto_fmt} → running cargo fmt (auto-fix)"
+    cargo fmt --all || { echo "pre-commit: cargo fmt failed" >&2; exit 1; }
+    # Re-stage only staged files that were reformatted
+    if STAGED=$(git diff --cached --name-only); then
+      if [[ -n "$STAGED" ]]; then
+        echo "$STAGED" | xargs -r git add --
+      fi
+    fi
+    ;;
+  0|false|FALSE|no|NO|off|OFF)
+    cargo fmt --all -- --check || { echo "pre-commit: cargo fmt check failed" >&2; exit 1; }
+    ;;
+  *)
+    # Unknown value → safest is check-only
+    cargo fmt --all -- --check || { echo "pre-commit: cargo fmt check failed" >&2; exit 1; }
+    ;;
+esac
 
 # 4) Docs guard (scaled): only require docs when core public API changed
 STAGED=$(git diff --cached --name-only)
@@ -60,12 +80,19 @@ if [[ -n "$CORE_API_CHANGED" ]]; then
   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
 
-# 5) Lockfile guard: ensure lockfile version is v3 (compatible with MSRV cargo)
+# 5) Lockfile guard: ensure lockfile version is v3 (current cargo format)
 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
+  # Normalize detected lockfile version (strip quotes/CR/whitespace)
+  VER_LINE=$(grep -n '^version = ' Cargo.lock | head -n1 | awk -F'= ' '{print $2}' | tr -d '\r' | tr -d '"' | xargs)
+  if [[ "$VER_LINE" != "3" ]]; then
+    # Determine pinned toolchain (normalize), fallback to rust-toolchain.toml if unset
+    _PINNED_RAW="${PINNED:-}"
+    if [[ -z "$_PINNED_RAW" ]]; then
+      _PINNED_RAW=$(awk -F '"' '/^channel/ {print $2}' rust-toolchain.toml 2>/dev/null || echo "")
+    fi
+    PINNED_NORM=$(printf "%s" "$_PINNED_RAW" | tr -d '\r' | xargs)
+    echo "pre-commit: Cargo.lock must be lockfile format v3 (found '$VER_LINE')." >&2
+    echo "Run: cargo +${PINNED_NORM} generate-lockfile" >&2
     exit 1
   fi
 fi

.githooks/pre-commit

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
-PINNED="${PINNED:-1.68.0}"
+PINNED="${PINNED:-1.71.1}"
+# MSRV floor for library checks (override with MSRV env)
+MSRV="${MSRV:-1.71.1}"
 
 for cmd in cargo rustup rg; do
   if ! command -v "$cmd" >/dev/null 2>&1; then
@@ -15,34 +17,76 @@ if [[ "${SKIP_HOOKS:-}" == 1 ]]; then
   exit 0
 fi
 
-echo "[pre-push] fmt"
-cargo +"$PINNED" fmt --all -- --check
+echo "[pre-push] fmt (default toolchain)"
+cargo fmt --all -- --check
 
-echo "[pre-push] clippy (workspace)"
-cargo +"$PINNED" clippy --all-targets -- -D warnings -D missing_docs
+echo "[pre-push] clippy (workspace, default toolchain)"
+cargo clippy --all-targets -- -D warnings -D missing_docs
 
-echo "[pre-push] tests (workspace)"
-cargo +"$PINNED" test --workspace
+echo "[pre-push] tests (workspace, default toolchain)"
+cargo 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
+echo "[pre-push] Testing against MSRV ${MSRV} (core libraries)"
+# If any participating crate declares a rust-version greater than MSRV, skip MSRV checks entirely.
+CORE_RV=$(awk -F '"' '/^rust-version/ {print $2}' crates/rmg-core/Cargo.toml 2>/dev/null || echo "")
+GEOM_RV=$(awk -F '"' '/^rust-version/ {print $2}' crates/rmg-geom/Cargo.toml 2>/dev/null || echo "")
+if { [[ -n "$CORE_RV" ]] && printf '%s\n%s\n' "$MSRV" "$CORE_RV" | sort -V | tail -n1 | grep -qx "$CORE_RV" && [[ "$CORE_RV" != "$MSRV" ]]; } \
+   || { [[ -n "$GEOM_RV" ]] && printf '%s\n%s\n' "$MSRV" "$GEOM_RV" | sort -V | tail -n1 | grep -qx "$GEOM_RV" && [[ "$GEOM_RV" != "$MSRV" ]]; }; then
+  echo "[pre-push] Skipping MSRV block: one or more crates declare rust-version > ${MSRV} (core=${CORE_RV:-unset}, geom=${GEOM_RV:-unset})"
 else
-  echo "[pre-push] MSRV toolchain $PINNED not installed. Install via: rustup toolchain install $PINNED" >&2
-  exit 1
+  if ! rustup run "$MSRV" cargo -V >/dev/null 2>&1; then
+    echo "[pre-push] MSRV toolchain ${MSRV} not installed. Install via: rustup toolchain install ${MSRV}" >&2
+    exit 1
+  fi
+  # Only run MSRV tests for crates that declare rust-version <= MSRV; skip otherwise.
+  msrv_ok() {
+    local crate="$1"
+    local rv
+    rv=$(awk -F '"' '/^rust-version/ {print $2}' "crates/${crate}/Cargo.toml" 2>/dev/null || echo "")
+    if [[ -z "$rv" ]]; then
+      return 0
+    fi
+    # If declared rust-version is greater than MSRV, skip.
+    if printf '%s\n%s\n' "$MSRV" "$rv" | sort -V | tail -n1 | grep -qx "$rv" && [[ "$rv" != "$MSRV" ]]; then
+      echo "[pre-push] Skipping MSRV test for ${crate} (rust-version ${rv} > MSRV ${MSRV})"
+      return 1
+    fi
+    # If crate depends on workspace rmg-core whose rust-version exceeds MSRV, skip as well
+    if grep -qE '^rmg-core\s*=\s*\{[^}]*path\s*=\s*"\.\./rmg-core"' "crates/${crate}/Cargo.toml" 2>/dev/null; then
+      local core_rv
+      core_rv=$(awk -F '"' '/^rust-version/ {print $2}' "crates/rmg-core/Cargo.toml" 2>/dev/null || echo "")
+      if [[ -n "$core_rv" ]] && printf '%s\n%s\n' "$MSRV" "$core_rv" | sort -V | tail -n1 | grep -qx "$core_rv" && [[ "$core_rv" != "$MSRV" ]]; then
+        echo "[pre-push] Skipping MSRV test for ${crate} (depends on rmg-core ${core_rv} > MSRV ${MSRV})"
+        return 1
+      fi
+    fi
+    return 0
+  }
+  if msrv_ok rmg-core; then cargo +"$MSRV" test -p rmg-core --all-targets; fi
+  if msrv_ok rmg-geom; then cargo +"$MSRV" test -p rmg-geom --all-targets; fi
 fi
 
-# Rustdoc warnings guard (core API)
-echo "[pre-push] rustdoc warnings gate (rmg-core)"
+# Rustdoc warnings guard (public crates)
+echo "[pre-push] rustdoc warnings gate (rmg-core @ $PINNED)"
 RUSTDOCFLAGS="-D warnings" cargo +"$PINNED" doc -p rmg-core --no-deps
+echo "[pre-push] rustdoc warnings gate (rmg-geom @ $PINNED)"
+RUSTDOCFLAGS="-D warnings" cargo +"$PINNED" doc -p rmg-geom --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
+# Forbid crate-level allow(missing_docs) in library source files, but allow in tests and build scripts
+if rg -n '#!\[allow\([^]]*missing_docs[^]]*\)\]' \
+  crates \
+  --glob 'crates/**/src/**/*.rs' \
+  --glob '!**/telemetry.rs' \
+  --glob '!**/tests/**' \
+  --glob '!**/build.rs' >/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
+  rg -n '#!\[allow\([^]]*missing_docs[^]]*\)\]' crates \
+    --glob 'crates/**/src/**/*.rs' \
+    --glob '!**/telemetry.rs' \
+    --glob '!**/tests/**' \
+    --glob '!**/build.rs' | cat >&2 || true
   exit 1
 fi
 if rg -n "\#\[unsafe\(no_mangle\)\]" crates >/dev/null; then

.githooks/pre-push

@@ -15,8 +15,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: false
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@1.71.1
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: |
@@ -31,19 +30,14 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: false
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@1.71.1
         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:
@@ -53,19 +47,13 @@ jobs:
       - 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: dtolnay/rust-toolchain@1.71.1
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: |
             .
-      - name: cargo test
-        env:
-          RUSTUP_TOOLCHAIN: stable
-        run: cargo test
+      - name: cargo test (workspace)
+        run: cargo test --workspace
       - name: PRNG golden regression (rmg-core)
         run: cargo test -p rmg-core --features golden_prng -- tests::next_int_golden_regression
 
@@ -101,20 +89,6 @@ jobs:
             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)
@@ -123,13 +97,7 @@ jobs:
       - 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: dtolnay/rust-toolchain@1.71.1
       - uses: Swatinem/rust-cache@v2
       - name: rustdoc warnings gate
-        env:
-          RUSTUP_TOOLCHAIN: stable
         run: RUSTDOCFLAGS="-D warnings" cargo doc -p rmg-core --no-deps

.githooks/pre-rebase

@@ -26,6 +26,12 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 - Respect determinism: preferably no random seeds without going through the Echo PRNG.
 - Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR; CI will expect a zero-warning, fully documented surface.
 
+### Git Hooks & Local CI
+- Install repo hooks once with `make hooks` (configures `core.hooksPath`).
+- Formatting: pre-commit auto-fixes with `cargo fmt` by default. Set `ECHO_AUTO_FMT=0` to run check-only instead.
+- Toolchain: pre-commit verifies your active toolchain matches `rust-toolchain.toml`.
+- Docs Guard: when core API files change, the hook requires updating `docs/execution-plan.md` and `docs/decision-log.md` (mirrors the CI check).
+
 ## Git Real
 1. **NEVER** use `--force` with any git command. If you think you need it, stop and ask the human for help.
 2. **NEVER** use rebase. Embrace messy distributed history; plain merges capture the truth, rebases rewrite it.

.github/workflows/ci.yml

@@ -22,6 +22,10 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 1. Clone the repo and run `cargo check` to ensure the Rust workspace builds.
 2. Read `docs/architecture-outline.md` and `docs/execution-plan.md`.
 3. Review `AGENTS.md` for collaboration norms before touching runtime code.
+4. Optional: develop inside the devcontainer for toolchain parity with CI.
+   - Open in VS Code → "Reopen in Container" (requires the Dev Containers extension).
+- The container includes Rust 1.71.1 (via rust-toolchain.toml), clippy/rustfmt, Node, and gh.
+- Post-create installs toolchain 1.71.1 (no override); wasm32 target and components are added to 1.71.1.
 
 ## Branching & Workflow
 - Keep `main` pristine. Create feature branches like `echo/<feature>` or `timeline/<experiment>`.
@@ -53,6 +57,14 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 - TypeScript tooling (when active) lives in `reference/typescript/`; follow local lint configs when reactivated.
 - Avoid non-deterministic APIs (no wall-clock, no uncontrolled randomness). Use Echo’s deterministic services.
 
+### Git Hooks (recommended)
+- Install repo hooks once: `make hooks` (configures `core.hooksPath` to `.githooks`).
+- Pre-commit runs:
+  - cargo fmt (auto-fix by default; set `ECHO_AUTO_FMT=0` for check-only)
+  - Toolchain pin verification (matches `rust-toolchain.toml`)
+  - A minimal docs-guard: when core API files change, it requires updating `docs/execution-plan.md` and `docs/decision-log.md` (mirrors CI)
+- To auto-fix formatting on commit: `ECHO_AUTO_FMT=1 git commit -m "message"`
+
 ## Communication
 - Major updates should land in `docs/execution-plan.md` and `docs/decision-log.md`; rely on GitHub discussions or issues for longer-form proposals.
 - Respect the temporal theme—leave the codebase cleaner for the next timeline traveler.