Merge remote-tracking branch 'origin/main' into HEAD

# Conflicts:
#	crates/revmc-codegen/src/compiler/translate/peephole.rs

Author: DaniPopes

.cargo/config.toml

@@ -1,3 +1,3 @@
 [alias]
-cl = "clippy --workspace --all-targets --features llvm"
+cl = "clippy --workspace --all-targets --features llvm,alloy-evm"
 docs = "doc --workspace --features llvm --no-deps --document-private-items"

.zed/settings.json

@@ -7,7 +7,7 @@
         },
         "cargo": {
           "allTargets": true,
-          "features": ["llvm"],
+          "features": ["llvm", "alloy-evm"],
           "sysroot": "discover",
         },
         "diagnostics": {

AGENTS.md

@@ -2,19 +2,24 @@
 
 ## Commands
 
+`--all-features` does not work. Just use default features and the following commands:
+
 ```bash
-cargo cl                                   # lint
-cargo fmt --all                            # format
-cargo docs                                 # check docs
-
-cargo nextest run --workspace              # test all
-cargo nextest run "test_name"              # test single
-cargo nextest run "statetest"              # test statetests
-SUBDIR=stRevertTest cargo nextest run "statetest" # test single statetest
+cargo cl                                                      # lint
+cargo fmt --all                                               # format
+cargo docs                                                    # check docs
+
+cargo nextest run --workspace                                 # test all
+cargo nextest run --workspace "test_name"                     # test single
+cargo nextest run --workspace "statetest"                     # test statetests
+SUBDIR=stRevertTest cargo nextest run --workspace "statetest" # test single statetest
 ```
 
 ## Architecture
-- `revmc` — main crate: EVM compiler, bytecode analysis, linker, and test infrastructure.
+
+- `revmc` — thin umbrella crate that re-exports codegen and runtime APIs.
+- `revmc-codegen` — EVM compiler, bytecode analysis, linker, and compiler test infrastructure.
+- `revmc-runtime` — runtime JIT/AOT backend, worker pool, artifact store, and revm integration.
 - `revmc-backend` — abstract compiler backend trait. `revmc-llvm` is the main implementation.
 - `revmc-builtins` — runtime builtins called by JIT-compiled code (host calls, gas accounting).
 - `revmc-context` — EVM execution context types bridging revm and compiled code.
@@ -31,6 +36,7 @@ during development.
 ```bash
 cargo r -- run --list                      # list available benchmarks
 cargo r -- run usdc_proxy                  # compile and run a benchmark
+cargo r -- run usdc_proxy -o tmp/dump      # compile and run a benchmark; dump files like opt.ll, remarks.txt to tmp/dump
 cargo r -- run usdc_proxy --parse-only     # parse and analyze only (no codegen)
 cargo r -- run usdc_proxy --display        # print parsed bytecode IR
 cargo r -- run usdc_proxy --dot            # render CFG as DOT/SVG
@@ -87,6 +93,11 @@ Use `cargo r -- run --list` to see available benchmark names.
 `./scripts/bench.py` is the unified benchmarking tool. It collects codegen line
 counts, compile times, jump resolution stats, and constant-input statistics.
 
+The script writes its full markdown output to `<dump_dir>/results.md` in
+addition to printing it to stdout. Summary tables hide changes within a noise
+threshold (1% for codegen, 5% for compile times); the `<details>` tables still
+show every change.
+
 ```bash
 ./scripts/bench.py /tmp/bench --diff main                          # codegen + compile time vs main
 ./scripts/bench.py /tmp/bench --diff main usdc_proxy seaport       # specific benchmarks
@@ -100,9 +111,55 @@ counts, compile times, jump resolution stats, and constant-input statistics.
 ./scripts/bench.py /tmp/bench --codegen-lines --jump-resolution    # combine multiple analyses
 ```
 
+## Bench-and-PR workflow
+
+When the user asks to "bench and open pr", "post results to pr", or whenever
+making a perf change that needs benchmark numbers in the PR description:
+
+1. Run `./scripts/bench.py <dump_dir> --diff <base>` (typically `--diff main`).
+2. Build the PR body **in a single bash command** that inlines
+   `<dump_dir>/results.md` VERBATIM. Do NOT reformat, summarize, drop
+   columns, or rewrite the numbers in the tables — `cat` the file as-is.
+3. Add prose explaining what the PR does ABOVE the inlined results, under a
+   `## Benchmarks` (or similar) heading.
+4. Under `## Benchmarks`, ABOVE the inlined `results.md`, write a short
+   textual summary of the headline numbers (e.g. the `**TOTAL**` row diffs
+   from the codegen + compile-time tables, plus any notable per-bench wins
+   or regressions worth calling out). Keep it to a few sentences or a tight
+   bullet list — this is the at-a-glance summary readers see before the
+   tables. The tables themselves stay verbatim.
+5. Update the PR with `gh pr edit <number> --body-file <body.md>`.
+
+Example — write the body file with prose, summary, and verbatim results in
+one shot:
+
+```bash
+{
+  cat <<'EOF'
+Short description of what this PR does and why.
+
+More prose: motivation, design notes, caveats, anything reviewers need.
+
+## Benchmarks
+
+Headline numbers vs `main`: jit size -7.5%, opt.s +2.9%, total compile time
++0.2%. `counter` regresses on opt.s (+26%); `seaport` is roughly flat.
+
+EOF
+  cat /tmp/bench/results.md
+} > /tmp/pr-body.md
+
+gh pr edit 123 --body-file /tmp/pr-body.md
+```
+
+The heredoc holds whatever prose + summary belongs in the PR; `cat results.md`
+appends the benchmark tables exactly as the script produced them.
+
 ## Important
 
-- NEVER summarize benchmark results. Always post the entire, unedited output.
+- NEVER alter or summarize the benchmark tables themselves — always post them
+  verbatim. A short textual summary of the headline numbers ABOVE the tables
+  (under `## Benchmarks`) is required.
 - NEVER delete or modify `./tmp/` — it contains manually generated IR/asm dumps used for comparison.
 - `tmp/dump/` contains dumps from `main`, `tmp/dump2/` contains dumps from the current branch.
   Use these for manual `diff` comparison of LLVM IR and assembly.