feat!: restart mega-evm as the Satin skeleton on the revm 40 forks

.cargo/mutants-infra.toml

@@ -0,0 +1,22 @@
+# cargo-mutants configuration for the test gates' own infrastructure.
+#
+# The canonical run (.cargo/mutants.toml) mutates mega-evm production code and excludes test
+# helpers as noise. By that rule the scenario runner (its transaction conversion and its
+# execute/commit loop) is helper code, but it is executable logic the benches and later tests rest
+# on. This config mutates exactly that; the production run keeps its exclusions unchanged.
+#
+# Selected by `scripts/mutation_test.sh infra`, which passes the file globs. See mutants/README.md.
+
+test_tool = "nextest"
+# mega-evm's tests cover the scenario runner.
+test_package = ["mega-evm"]
+
+# Same pinned feature set as the production run, so the two generate comparable mutants.
+additional_cargo_args = ["--all-features"]
+
+# No `**/test_utils/**` exclusion here: the scenario runner living under it is the subject.
+exclude_globs = ["**/generated/**"]
+
+minimum_test_timeout = 120
+timeout_multiplier = 3.0
+copy_target = true

.cargo/mutants.toml

@@ -4,8 +4,15 @@
 # (scripts/mutation_test.sh + scripts/mutation_gate.py) layers diff-scoping,
 # suppression metadata, and PR gating on top of it. See mutants/README.md.
 #
-# Scope: only `mega-evm` is mutated. `mega-system-contracts` produces 0 mutants
-# (its src/ is generated bytecode artifacts), so it is intentionally absent.
+# Scope: only `mega-evm` production code is mutated. `mega-system-contracts`
+# produces 0 mutants (its src/ is generated bytecode artifacts), so it is
+# intentionally absent.
+#
+# There is a second scope, .cargo/mutants-infra.toml (`scripts/mutation_test.sh
+# infra`): the code that implements the test gates themselves, which the
+# `**/test_utils/**` exclusion below and the single `test_package` would
+# otherwise leave unmutated. The two scopes are disjoint and are gated
+# separately; this one keeps its exclusions.
 
 # Run tests with nextest (the project's standard runner) and restrict the test
 # command to the mutated package for speed.

.github/workflows/benchmark.yml

@@ -199,7 +199,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        target: [revm_bench, mega_bench, block_bench, transact, comp_cost, ctt, attack_replay]
+        # The Satin bench set: `transact`, `corpus` and `factory`, until the
+        # suite is rebuilt on Satin, which restores the full list. Scheduled and
+        # comment-triggered runs use the default branch's copy of this file.
+        target: [corpus, factory, transact]
     steps:
       - uses: actions/checkout@v4
         with:

.github/workflows/exec-spec.yml

@@ -0,0 +1,165 @@
+name: Execution-spec tests
+
+# Runs the execution-spec-test fixtures with the revm fork's own runner (`scripts/run-tests.sh`,
+# release mode) at the fork tag Cargo.lock pins, then counts the state tests the runner executes
+# and skips for Osaka (the main fixtures) and Amsterdam (the glamsterdam devnet fixtures) and
+# checks them against the numbers pinned below.
+#
+# An interim gate until the state-test tool is ported to Satin. It checks the fork MegaEvm runs
+# on, not MegaEvm. Not a required check.
+
+on:
+  workflow_dispatch:
+  # GitHub fires a schedule only from the default branch's copy of a workflow: this one runs
+  # weekly once `satin` is the default branch. Until then, dispatch it by hand on `satin`.
+  schedule:
+    - cron: "0 4 * * 1" # Weekly, Monday 4:00 UTC
+  pull_request:
+    paths:
+      - Cargo.lock
+      - Cargo.toml
+      - .github/workflows/exec-spec.yml
+  push:
+    branches: [satin]
+    paths:
+      - Cargo.lock
+      - Cargo.toml
+      - .github/workflows/exec-spec.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  exec-spec:
+    name: execution-spec tests
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    env:
+      # State tests the runner executes and skips, per fork, on the fixture releases
+      # `scripts/run-tests.sh` downloads at the pinned tag (main v5.4.0 develop fixtures,
+      # glamsterdam devnet v8.1.0). The skipped ones are the create-collision fixtures with
+      # storage the runner skips by name, and expected-exception transactions it cannot build
+      # (bad signatures, blob-hash creates). A change that moves the fork pin, and with it the
+      # runner or the fixtures, updates them.
+      OSAKA_EXECUTED: "19465"
+      OSAKA_SKIPPED: "52"
+      AMSTERDAM_EXECUTED: "15754"
+      AMSTERDAM_SKIPPED: "72"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Read the fork pin from Cargo.lock
+        id: pin
+        run: |
+          sources=$(grep -o 'git+https://github.com/megaeth-labs/revm?tag=[^"#]*#[0-9a-f]*' Cargo.lock | sort -u)
+          if [ "$(printf '%s\n' "$sources" | grep -c .)" -ne 1 ]; then
+            printf 'expected exactly one revm fork revision in Cargo.lock, found:\n%s\n' "$sources" >&2
+            exit 1
+          fi
+          tag=${sources#*tag=}
+          tag=${tag%%#*}
+          commit=${sources##*#}
+          echo "fork tag $tag at $commit"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "commit=$commit" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v4
+        with:
+          repository: megaeth-labs/revm
+          ref: ${{ steps.pin.outputs.tag }}
+          path: revm-fork
+          persist-credentials: false
+
+      - name: Check the tag names the locked revision
+        working-directory: revm-fork
+        env:
+          COMMIT: ${{ steps.pin.outputs.commit }}
+        run: test "$(git rev-parse HEAD)" = "$COMMIT"
+
+      - name: Read the fork's toolchain
+        id: rust
+        working-directory: revm-fork
+        run: echo "channel=$(sed -n 's/^channel = "\(.*\)"$/\1/p' rust-toolchain.toml)" >> "$GITHUB_OUTPUT"
+
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.rust.outputs.channel }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: revm-fork
+          cache-on-failure: true
+
+      - name: Run the fork's execution-spec suites
+        working-directory: revm-fork
+        run: ./scripts/run-tests.sh clean cargo release
+
+      - name: Count the Osaka and Amsterdam state tests
+        working-directory: revm-fork
+        run: |
+          set -euo pipefail
+          # State tests a fixture tree defines for a fork: one per post-state entry, keyed by the
+          # fixtures' fork name (`Osaka`). `$fork` in the jq program is a jq variable.
+          # shellcheck disable=SC2016
+          defined() {
+            find "$1" -name '*.json' -print0 \
+              | xargs -0 jq -r --arg fork "$2" '[.[] | .post[$fork] // [] | length] | add // 0' \
+              | awk '{ n += $1 } END { print n + 0 }'
+          }
+          # The script's run prints no counts, so the two state-test trees run once more with the
+          # runner's per-test JSON outcome on stderr (about a minute of the job). The build is
+          # the one the script made.
+          outcomes() {
+            cargo run --release -p revme -- statetest --json-outcome --omit-progress "$1" \
+              2> outcomes.jsonl > /dev/null
+          }
+          # State tests the runner executed for a fork, keyed by revm's spec id (`OSAKA`). Other
+          # stderr lines are not JSON and are dropped. `$spec` in the jq program is a jq variable.
+          # shellcheck disable=SC2016
+          executed() {
+            jq -Rr --arg spec "$1" 'fromjson? | select(type == "object" and .fork == $spec) | .test' \
+              outcomes.jsonl | wc -l | tr -d ' '
+          }
+          check() {
+            local label=$1 dir=$2 fork=$3 spec=$4 want_executed=$5 want_skipped=$6
+            local total ran skipped
+            # `check` runs under `||`, where errexit is off, so every step is guarded here: a
+            # counting pipeline that prints the expected number and then fails would otherwise
+            # pass the comparison below. Each command substitution is assigned on its own so the
+            # assignment carries the command's status (`local total=$(...)` would mask it).
+            if ! total=$(defined "$dir" "$fork"); then
+              echo "::error::$label: counting the state tests $dir defines failed"
+              return 1
+            fi
+            if ! outcomes "$dir"; then
+              echo "::error::$label: the runner failed on $dir"
+              return 1
+            fi
+            if ! ran=$(executed "$spec"); then
+              echo "::error::$label: counting the state tests the runner executed for $spec failed"
+              return 1
+            fi
+            skipped=$((total - ran))
+            echo "$label: $ran executed, $skipped skipped of $total defined ($dir)"
+            echo "| $label | $ran | $skipped | $total |" >> "$GITHUB_STEP_SUMMARY"
+            if [ "$ran" != "$want_executed" ] || [ "$skipped" != "$want_skipped" ]; then
+              echo "::error::$label: expected $want_executed executed and $want_skipped skipped, got $ran and $skipped"
+              return 1
+            fi
+          }
+          {
+            echo "| Fixtures | Executed | Skipped | Defined |"
+            echo "|---|---:|---:|---:|"
+          } >> "$GITHUB_STEP_SUMMARY"
+          status=0
+          check Osaka test-fixtures/main/develop/state_tests Osaka OSAKA \
+            "$OSAKA_EXECUTED" "$OSAKA_SKIPPED" || status=1
+          check Amsterdam test-fixtures/devnet/state_tests Amsterdam AMSTERDAM \
+            "$AMSTERDAM_EXECUTED" "$AMSTERDAM_SKIPPED" || status=1
+          exit "$status"

.github/workflows/mutation.yml

@@ -1,11 +1,13 @@
 name: Mutation Testing
 
-# All mutation-testing CI lives here. Three concerns, one file:
+# All mutation-testing CI lives here. Four concerns, one file:
 #   * cargo-mutants gate   — generic operators (diff-scoped on PRs, full nightly)
+#   * infrastructure gate  — the same operators on the code that implements the
+#                            test gates, which the production scope excludes
 #   * spec-gate            — universalmutator + comby custom operators for
 #                            backward-compat spec gates (diff PR + nightly sweep)
 #   * suppression hygiene  — flag suppressions that no longer match a live mutant
-# All three share the scorer scripts/mutation_gate.py. See mutants/README.md.
+# All four share the scorer scripts/mutation_gate.py. See mutants/README.md.
 
 on:
   workflow_dispatch:
@@ -125,6 +127,64 @@ jobs:
             mutation-report.md
           if-no-files-found: ignore
 
+  # ── cargo-mutants: the test gates' own infrastructure ──────────────────────
+  # The second mutation scope (.cargo/mutants-infra.toml): the scenario runner's
+  # transaction conversion and execute/commit loop. The production scope
+  # excludes test helpers as noise, so this executable logic is never mutated
+  # there. 39 mutants today, so the whole set runs rather than a diff
+  # slice. Informational: it is not a required check.
+  infra-mutants:
+    name: cargo-mutants infrastructure
+    needs: changes
+    # Always on nightly/dispatch; on PRs only when the mutated code, its
+    # configuration or the driver changed.
+    if: |
+      always() &&
+      (github.event_name != 'pull_request' || needs.changes.outputs.infra == 'true')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install cargo-nextest
+        uses: taiki-e/install-action@nextest
+
+      - name: Install cargo-mutants
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-mutants@27.1.0
+
+      - name: Warm build cache
+        run: cargo nextest run -p mega-evm --all-features --no-run
+
+      - name: Run mutation testing
+        env:
+          OUT_DIR: target/mutants-infra
+        run: scripts/mutation_test.sh infra
+
+      - name: Score and gate
+        run: |
+          python3 scripts/mutation_gate.py report \
+            --results target/mutants-infra/mutants.out \
+            --suppressions mutants/suppressions.toml \
+            --summary "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload mutation artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-results-infra
+          path: target/mutants-infra/mutants.out
+          if-no-files-found: ignore
+
   # ── spec-gate: diff-scoped blocking gate on PRs ────────────────────────────
   # Only files+lines the PR changed are mutated, so most PRs generate zero
   # spec-gate mutants and this is near-instant.
@@ -260,12 +320,14 @@ jobs:
 
   # ── suppression hygiene: gate on relevant PR changes, plus nightly ─────────
   # `changes` scopes the hygiene job to PRs that could orphan a suppression
-  # (suppressions, operators, or src edits); nightly/dispatch always run it.
+  # (suppressions, operators, or src edits) and the infrastructure job to PRs
+  # that touch its scope; nightly/dispatch always run both.
   changes:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-24.04
     outputs:
       hygiene: ${{ steps.filter.outputs.hygiene }}
+      infra: ${{ steps.filter.outputs.infra }}
     steps:
       - uses: dorny/paths-filter@v3
         id: filter
@@ -275,6 +337,11 @@ jobs:
               - 'mutants/suppressions.toml'
               - 'mutants/operators/**'
               - 'crates/mega-evm/src/**'
+            infra:
+              - '.cargo/mutants-infra.toml'
+              - 'crates/mega-evm/src/test_utils/scenario.rs'
+              - 'scripts/mutation_gate.py'
+              - 'scripts/mutation_test.sh'
 
   orphan-suppressions:
     name: suppression hygiene
@@ -306,19 +373,30 @@ jobs:
           sudo curl -fsSL https://github.com/comby-tools/comby/releases/download/1.8.1/comby-1.8.1-x86_64-linux -o /usr/local/bin/comby
           sudo chmod +x /usr/local/bin/comby
           comby -version
-      - name: Build the full mutant universe (both engines)
+      - name: Build the full mutant universe (both engines, both scopes)
         run: |
-          # --package mega-evm: match the driver's scope (otherwise --list also
-          #   covers the CLI bins in the virtual workspace's default-members, so a
+          # --package mega-evm: match the driver's production scope (otherwise --list
+          #   also covers the CLI bins in the virtual workspace's default-members, so a
           #   stale mega-evm suppression could be kept alive by a same-named mutant
           #   in another crate).
           # No --exclude-re here, so function-suppressed mutants are included —
           #   giving the complete universe to validate suppressions against.
           # --colors never: CI forces CARGO_TERM_COLOR=always, which would otherwise
           #   embed ANSI codes and break exact suppression matching.
           cargo mutants --list --package mega-evm --colors never > universe.txt
-          python3 scripts/umutate.py plan --packs spec-gate \
-            | grep -oE 'crates/mega-evm/[^:]+:[0-9]+:[0-9]+: spec-gate .*' >> universe.txt
+          # The infrastructure scope is a second mutant population and a suppression may live in
+          # it, so it joins the universe. Listed through the driver, so its file list stays in
+          # one place, with SUPPRESS=/dev/null so the driver emits no --exclude-re and function-
+          # suppressed mutants stay in the universe here too. The grep drops the driver's
+          # trailing progress lines and fails the step if the scope lists nothing.
+          SUPPRESS=/dev/null scripts/mutation_test.sh infra --list --colors never \
+            | grep -oE 'crates/[^:]+:[0-9]+:[0-9]+: .*' >> universe.txt
+          # The plan runs on its own so a planner failure still fails the step.
+          # Its mutant lines are grepped separately: a single-spec engine (the
+          # satin branch) has no spec gates and the pack finds nothing. grep's
+          # "no match" (exit 1) is accepted; a grep error (exit 2) still fails.
+          python3 scripts/umutate.py plan --packs spec-gate > spec-gate-plan.txt
+          grep -oE 'crates/mega-evm/[^:]+:[0-9]+:[0-9]+: spec-gate .*' spec-gate-plan.txt >> universe.txt || [ $? -eq 1 ]
           echo "universe: $(wc -l < universe.txt) mutants"
       - name: Check for orphan suppressions
         run: |

.github/workflows/replay-bench.yml

@@ -104,6 +104,11 @@ jobs:
   bench:
     name: Replay throughput
     needs: prepare
+    # Disabled on the satin branch: this job builds `state-test`, which is not a
+    # workspace member until it is ported to the Satin engine; the port removes
+    # this line. (`compare` needs this job, so it is skipped with it.) Scheduled
+    # and comment-triggered runs use the default branch's copy of this file.
+    if: false
     runs-on: blacksmith-32vcpu-ubuntu-2404
     timeout-minutes: 90
     permissions: