feat!(ethexe): malachite

.claude/hooks/claude-md-review.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Stop hook: ask Sonnet to review uncommitted changes against CLAUDE.md
+# at the project root. Exits 2 with findings on stderr if violations are
+# found; exits 0 silently otherwise. Recursion-safe via the
+# CLAUDE_MD_REVIEW_RUNNING env-var guard.
+
+# Recursion guard: when our own `claude -p` subprocess fires its own Stop,
+# the harness re-invokes this script. We exit immediately in that case.
+if [ -n "${CLAUDE_MD_REVIEW_RUNNING:-}" ]; then
+    exit 0
+fi
+
+set -uo pipefail
+
+# Anchor at the git toplevel so the review still fires from any subdir.
+project_root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$project_root"
+
+# Cheap pre-filter — skip the review when no Rust/Solidity/Toml changed.
+# We capture into a variable instead of `grep -q` because pipefail + grep's
+# early-exit makes upstream commands die from SIGPIPE, which would invert
+# the match check.
+changed_files=$( { git diff --name-only HEAD 2>/dev/null;
+                   git ls-files --others --exclude-standard 2>/dev/null; } )
+if ! printf '%s\n' "$changed_files" | grep -E '\.(rs|sol|toml)$' >/dev/null; then
+    exit 0
+fi
+
+# Build a unified diff covering tracked changes + new file content.
+diff=$(git diff --no-color HEAD 2>/dev/null || true)
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    [ ! -f "$f" ] && continue
+    case "$f" in
+        *.rs|*.sol|*.toml) ;;
+        *) continue ;;
+    esac
+    diff+=$'\n--- /dev/null\n+++ b/'"$f"$'\n'
+    diff+=$(awk '{print "+" $0}' "$f")
+    diff+=$'\n'
+done < <(git ls-files --others --exclude-standard 2>/dev/null)
+
+if [ -z "${diff//[[:space:]]/}" ]; then
+    exit 0
+fi
+
+# Dry-run hatch — runs everything except the Sonnet call. For testing.
+if [ -n "${CLAUDE_MD_REVIEW_DRY_RUN:-}" ]; then
+    echo "dry-run: $(printf '%s' "$diff" | wc -l) diff lines, would call Sonnet" >&2
+    exit 0
+fi
+
+prompt=$(cat <<'PROMPT'
+You are a CLAUDE.md compliance linter for the gear repository. The project
+root is the current working directory.
+
+1. Read CLAUDE.md at the project root for the rules. Particularly enforce:
+   - Comment & Doc Sizing tiers (Tiny=1 line for inline body comments;
+     Small=≤5 for private items; Medium=≤20 for public items;
+     Large=≤200 for crate-level)
+   - Test timeout cap (no >120_000 ms without explicit user permission)
+   - `unwrap_or` / `unwrap_or_default` / `unwrap_or_else` ban in
+     production code (tests/mocks excluded)
+   - Any other concrete rule stated in CLAUDE.md
+
+2. Review the diff below for any rule violations.
+
+3. Output format — strict:
+   - If NO violations, output the single line `OK` and nothing else.
+   - Otherwise, one violation per line as:
+     `path:line — rule violated — what to change`
+   - No headers, summaries, or commentary outside that format.
+
+DIFF:
+PROMPT
+)
+prompt+=$'\n'"$diff"
+
+# Spawn Sonnet headlessly. Auth inherits from the user's environment.
+# CLAUDE_MD_REVIEW_RUNNING=1 short-circuits this same script when the
+# spawned `claude -p` fires its own Stop event.
+review=$(CLAUDE_MD_REVIEW_RUNNING=1 claude -p "$prompt" \
+    --model sonnet \
+    --output-format text \
+    --max-budget-usd 0.50 \
+    --add-dir "$(pwd)" 2>/dev/null) || exit 0
+
+trimmed=$(printf '%s' "$review" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+if [ "$trimmed" = "OK" ] || [ -z "$trimmed" ]; then
+    exit 0
+fi
+
+{
+    echo "CLAUDE.md compliance review (Sonnet) — possible issues:"
+    echo
+    echo "$review"
+    echo
+    echo "Apply judgment — fix genuine violations of project rules, but skip"
+    echo "suggestions that contradict explicit user requests in the current"
+    echo "session (e.g. user asked for a verbose comment)."
+} >&2
+exit 2

.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/claude-md-review.sh",
+            "timeout": 120,
+            "statusMessage": "Reviewing changes against CLAUDE.md..."
+          }
+        ]
+      }
+    ]
+  }
+}

.config/nextest.toml

@@ -10,6 +10,14 @@ chmod +x target/release/gear
 leak-timeout = { period = "5s", result = "fail" }
 slow-timeout = { period = "1m", terminate-after = 5 }
 
+# ethexe-service tests spawn Anvil child processes plus a malachite
+# engine with libp2p sockets and a RocksDB WAL. Graceful tear-down of
+# the whole stack can exceed the default 5s leak window; treat leaks
+# as a non-fatal warning here so the suite is stable.
+[[profile.default.overrides]]
+filter = 'package(ethexe-service)'
+leak-timeout = { period = "10s", result = "pass" }
+
 [profile.default.junit]
 path = "junit.xml"
 store-success-output = false

CLAUDE.md

@@ -351,6 +351,30 @@ Errors are encoded as little-endian u32. Code `0xffff` is reserved for SyscallUs
 - `cargo nextest` is the test runner (not `cargo test`), except for doc tests
 - `cargo hakari` manages workspace dependency deduplication — run `make workspace-hack` after dependency changes
 
+### Test Timeouts
+
+Hard rule: **never set a test timeout above 2 minutes (`120_000` ms) without the user's explicit permission.** When a test legitimately needs more — either modernize it to fit under 2 minutes (mock heavy I/O, shrink the simulated chain, drive events explicitly instead of waiting on wall-clock pacing), or stop and ask the user before bumping the cap. A timeout is a symptom; the fix is the test logic, not the limit.
+
+### `unwrap_or` and friends in production code
+
+Hard rule: **outside tests and mocks, do not use `unwrap_or` / `unwrap_or_default` / `unwrap_or_else` to paper over an `Option`/`Result` whose `None`/`Err` branch is supposedly "impossible".** If an invariant guarantees the value is present, encode that with a real error (`ok_or_else(|| anyhow!("..."))`, `expect("invariant")`) so a violation becomes a loud, debuggable failure rather than silent fall-through to a sentinel. Reach for `unwrap_or*` only when the fallback is a meaningful semantic value — not when you're just trying to keep the type-checker happy. Tests, mocks, and explicit user direction can override this.
+
+### Comment & Doc Sizing
+
+Default rule (overridable per-session by the user). Comment length scales with the importance of the item:
+
+| Tier | Max length | Applies to |
+|------|------------|------------|
+| Large (≤200 lines) | full prose | crate-level docs (`//!` at the top of `lib.rs` / `main.rs`): purpose, usage, structure, surface-level implementation notes |
+| Medium (≤20 lines) | substantive | public structs / functions / modules: purpose, usage, structure, surface-level implementation notes |
+| Small (≤5 lines) | brief | private structs / functions / modules |
+| Tiny (1 line) | one-liner | inline comments inside function bodies |
+
+Rules of thumb:
+- A comment that exceeds its tier is a smell.
+- Don't restate what well-named identifiers already say.
+- Inline comments justify *why*, not *what*. If the why is obvious, drop the comment.
+
 ## GitHub PR Review
 
 When asked to review a PR (e.g. `@claude review` in a PR comment):