feat: coverage-replayer — minimal mainnet block set maximizing mega-evm branch coverage

.gitignore

@@ -6,4 +6,10 @@
 .mcp.json
 
 # database
-validator-data
+validator-data
+
+# coverage-replayer run data & artifacts (transferred out-of-band, never via git)
+/data/
+*.profraw
+*.pid
+*.log

AGENTS.md

@@ -5,7 +5,7 @@ This file provides guidance to AI agents (e.g., Claude Code, Codex, Cursor, etc.
 ## Project Overview
 
 Stateless validator for MegaETH — validates blocks using SALT witness data without requiring full chain state.
-The workspace contains two binaries: `stateless-validator` (chain-following validator) and `debug-trace-server` (RPC server for debug/trace methods).
+The workspace contains three binaries: `stateless-validator` (chain-following validator), `debug-trace-server` (RPC server for debug/trace methods), and `coverage-replayer` (offline tool that derives the minimal mainnet block set maximizing mega-evm branch coverage).
 See `README.md` for detailed documentation and quickstart.
 
 ## Build & Development Commands
@@ -34,14 +34,16 @@ The project uses nightly `2026-02-03` toolchain (edition 2024, rust-version 1.95
 
 ## Workspace Structure
 
-| Crate                  | Path                          | Purpose                                                                                    |
-| ---------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `stateless-core`       | `crates/stateless-core`       | Storage traits, pipeline, EVM execution, SALT witness handling, chain spec, error types    |
-| `stateless-db`         | `crates/stateless-db`         | redb-backed persistence: table definitions, read/write helpers, `ContractCache`            |
-| `stateless-common`     | `crates/stateless-common`     | RPC client, metrics/logging utilities, witness size estimation                             |
-| `stateless-test-utils` | `crates/stateless-test-utils` | Test fixtures (blocks, witnesses, contracts) and env-var lock for integration tests        |
-| `stateless-validator`  | `bin/stateless-validator`     | Main binary: chain sync, parallel validation workers (`app.rs` / `workers.rs` / `main.rs`) |
-| `debug-trace-server`   | `bin/debug-trace-server`      | Standalone RPC server for debug/trace methods                                              |
+| Crate                  | Path                          | Purpose                                                                                                                                                                                  |
+| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stateless-core`       | `crates/stateless-core`       | Storage traits, pipeline, EVM execution, SALT witness handling, chain spec, error types                                                                                                  |
+| `stateless-db`         | `crates/stateless-db`         | redb-backed persistence: table definitions, read/write helpers, `ContractCache`                                                                                                          |
+| `stateless-common`     | `crates/stateless-common`     | RPC client, metrics/logging utilities, witness size estimation                                                                                                                           |
+| `stateless-test-utils` | `crates/stateless-test-utils` | Test fixtures (blocks, witnesses, contracts) and env-var lock for integration tests                                                                                                      |
+| `stateless-r2`         | `crates/stateless-r2`         | Shared R2 (S3) witness primitives: SigV4 signer, object-key layout, endpoint parsing, signed PUT; consumed by mega-reth's uploaders (write) and the validator's R2 witness source (read) |
+| `stateless-validator`  | `bin/stateless-validator`     | Main binary: chain sync, parallel validation workers (`app.rs` / `workers.rs` / `main.rs`)                                                                                               |
+| `debug-trace-server`   | `bin/debug-trace-server`      | Standalone RPC server for debug/trace methods                                                                                                                                            |
+| `coverage-replayer`    | `bin/coverage-replayer`       | Offline coverage tool: replays blocks under LLVM branch instrumentation (`backfill`), dedups per-block coverage bitmaps into patterns, and computes the minimal covering block set (`set-cover` / `report` / `inspect` / `merge`). Requires the instrumented `[profile.coverage]` build |
 
 Additional directories: `test_data/` (integration test fixtures including genesis config), `audits/` (security audit reports).
 
@@ -109,26 +111,26 @@ The server includes an HTTP response cache (`quick_cache`) for pre-serialized JS
 
 ### Key Source Files
 
-| File                                                                                           | Purpose                                                                  |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `crates/stateless-core/src/pipeline/{mod,config,traits,fetcher,divergence,advancer,worker}.rs` | Generic three-stage pipeline split by responsibility                     |
-| `crates/stateless-core/src/executor.rs`                                                        | Block validation and EVM replay (generic over the `BlockInput` projection) |
-| `crates/stateless-core/src/evm_database.rs`                                                    | WitnessDatabase implementing `revm::DatabaseRef`                         |
-| `crates/stateless-core/src/db.rs`                                                              | Shared storage traits (`ContractStore`, `ChainStore`) + `StoreError` / `StoreResult`                   |
-| `crates/stateless-core/src/withdrawals.rs`                                                     | Withdrawal validation and MPT witness handling                           |
-| `crates/stateless-db/src/{lib,tables,helpers,serialize,cache}.rs`                              | Shared redb tables, helpers, serialization, and `ContractCache`          |
-| `crates/stateless-common/src/rpc_client.rs`                                                    | RPC client for blocks, witnesses, and bytecode                           |
-| `crates/stateless-common/src/metrics.rs`                                                       | RpcMethod, RpcMetrics, RpcClientConfig                                   |
-| `bin/stateless-validator/src/{main,app,workers,chain_sync,validator_db,metrics}.rs`            | Thin entry, CLI/startup wiring, pipeline+reporter, fetcher/processor, DB |
-| `bin/debug-trace-server/src/chain_sync.rs`                                                     | TraceFetcher, TraceProcessor, TraceHooks                                 |
-| `bin/debug-trace-server/src/rpc_service.rs`                                                    | RPC method definitions and handlers                                      |
-| `bin/debug-trace-server/src/data_provider.rs`                                                  | Block data fetching with single-flight coalescing                        |
-| `bin/debug-trace-server/src/server_db.rs`                                                      | Defines + implements the bin-local `BlockStore` trait (backed by `stateless-db`)            |
+| File                                                                                           | Purpose                                                                              |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `crates/stateless-core/src/pipeline/{mod,config,traits,fetcher,divergence,advancer,worker}.rs` | Generic three-stage pipeline split by responsibility                                 |
+| `crates/stateless-core/src/executor.rs`                                                        | Block validation and EVM replay (generic over the `BlockInput` projection)           |
+| `crates/stateless-core/src/evm_database.rs`                                                    | WitnessDatabase implementing `revm::DatabaseRef`                                     |
+| `crates/stateless-core/src/db.rs`                                                              | Shared storage traits (`ContractStore`, `ChainStore`) + `StoreError` / `StoreResult` |
+| `crates/stateless-core/src/withdrawals.rs`                                                     | Withdrawal validation and MPT witness handling                                       |
+| `crates/stateless-db/src/{lib,tables,helpers,serialize,cache}.rs`                              | Shared redb tables, helpers, serialization, and `ContractCache`                      |
+| `crates/stateless-common/src/rpc_client.rs`                                                    | RPC client for blocks, witnesses, and bytecode                                       |
+| `crates/stateless-common/src/metrics.rs`                                                       | RpcMethod, RpcMetrics, RpcClientConfig                                               |
+| `bin/stateless-validator/src/{main,app,workers,chain_sync,validator_db,metrics}.rs`            | Thin entry, CLI/startup wiring, pipeline+reporter, fetcher/processor, DB             |
+| `bin/debug-trace-server/src/chain_sync.rs`                                                     | TraceFetcher, TraceProcessor, TraceHooks                                             |
+| `bin/debug-trace-server/src/rpc_service.rs`                                                    | RPC method definitions and handlers                                                  |
+| `bin/debug-trace-server/src/data_provider.rs`                                                  | Block data fetching with single-flight coalescing                                    |
+| `bin/debug-trace-server/src/server_db.rs`                                                      | Defines + implements the bin-local `BlockStore` trait (backed by `stateless-db`)     |
 
 ## Test Organization
 
 Unit tests are embedded in source files alongside the code they test.
-Integration tests live in `bin/debug-trace-server/tests/` (6 modules: cache_metrics, block_tag, consistency, performance, timing_header, prune) and in `bin/stateless-validator/tests/integration.rs` (CLI parsing, mock-RPC pipeline, mainnet single-block validation).
+Integration tests live in `bin/debug-trace-server/tests/` (5 modules: cache_metrics, block_tag, consistency, performance, timing_header), in `bin/stateless-validator/tests/integration.rs` (CLI parsing, mock-RPC pipeline, mainnet single-block validation), and in `bin/coverage-replayer/tests/replay_fixtures.rs` (worker replay glue over the `test_data/mainnet` fixtures).
 Test data (block JSON files, contract bytecode, witness data) is stored in `test_data/`.
 
 ## Version Control

Cargo.toml

@@ -1,10 +1,12 @@
 [workspace]
 members = [
+    "bin/coverage-replayer",
     "bin/debug-trace-server",
     "bin/stateless-validator",
     "crates/stateless-common",
     "crates/stateless-core",
     "crates/stateless-db",
+    "crates/stateless-r2",
     "crates/stateless-test-utils",
 ]
 resolver = "2"
@@ -62,6 +64,7 @@ revm-inspectors = { version = "0.27.3", features = ["std", "js-tracer"], default
 base64 = { version = "0.22", default-features = false }
 bincode = { version = "2.0", features = ["serde", "alloc"], default-features = false }
 bytes = "1.11"
+chrono = { version = "0.4", default-features = false }
 clap = { version = "4.6", features = ["derive", "env", "std"], default-features = false }
 dashmap = { version = "6.1", default-features = false }
 dotenvy = "0.15"
@@ -70,6 +73,8 @@ eyre = { version = "0.6", features = ["auto-install"], default-features = false
 fastrand = { version = "2.4", default-features = false }
 futures = { version = "0.3", default-features = false }
 hashbrown = { version = "0.16", default-features = false }
+hex = { version = "0.4", default-features = false }
+hmac = { version = "0.12", default-features = false }
 http = "1.4"
 http-body = "1.0"
 http-body-util = "0.1"
@@ -82,15 +87,17 @@ metrics = "0.24"
 metrics-derive = "0.1"
 metrics-exporter-prometheus = { version = "0.18", features = ["http-listener"], default-features = false }
 num_cpus = "1.17"
+percent-encoding = { version = "2.3", default-features = false }
 pin-project-lite = "0.2"
 quick_cache = { version = "0.6", default-features = false }
 rayon = "1.11"
 redb = "4.0"
-reqwest = { version = "0.13", features = ["json", "blocking"], default-features = false }
+reqwest = { version = "0.12", default-features = false }
 rolling-file = "0.2"
 rustc-hash = { version = "2.1", default-features = false }
 serde = { version = "1.0", default-features = false, features = ["alloc", "derive"] }
 serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
+sha2 = { version = "0.10", default-features = false }
 tempfile = { version = "3.27", default-features = false }
 thiserror = { version = "2.0", default-features = false }
 tokio = { version = "1.51", features = ["rt-multi-thread", "signal"], default-features = false }
@@ -113,3 +120,18 @@ opt-level = 3
 debug-assertions = true
 incremental = true
 debug = true
+
+# Instrumented builds for coverage-replayer: coverage only cares about "was it
+# executed", so trade peak runtime speed for much faster builds (no LTO, many
+# codegen units). Do NOT add `-C link-dead-code` (it monomorphizes dead generic
+# code and fails const-eval asserts in revm). Pass an explicit --target so
+# RUSTFLAGS skips host artifacts (otherwise instrumented proc-macros make every
+# rustc invocation drop default_*.profraw files into the cwd). Build with:
+#   RUSTFLAGS="-C instrument-coverage -Z coverage-options=branch" \
+#     cargo build --profile coverage -p coverage-replayer --features coverage \
+#       --target "$(rustc -vV | sed -n 's/host: //p')"
+[profile.coverage]
+inherits = "release"
+opt-level = 2
+lto = "off"
+codegen-units = 16