feat(evm): symbolic-assist worker (concolic-lite v1) for coverage-guided fuzzing

Adds a directed-mutation worker that periodically replays a corpus seed under a
branch-trace inspector, finds the deepest unseen opposite-side branch ("frontier"),
and proposes ABI-aware calldata rewrites that flip the branch — without invoking
an SMT solver. Inspired by Echidna's Echidna.SymExec.Exploration and the
SaferMaker writeup (https://hackmd.io/@SaferMaker/EVM-Sym-Exec).

Architecture:

- BranchTraceInspector (crates/evm/evm/src/inspectors/branch_trace.rs):
  observation-only REVM Inspector that records every JUMPI together with the
  immediately-preceding compare opcode (EQ/LT/GT/SLT/SGT/ISZERO) and its
  concrete operands. Uses the same edge-id hashing as EdgeCovInspector so
  frontier ids can be looked up directly in the corpus history map.

- crates/evm/evm/src/executors/symexec/:
  - types.rs: FrontierKey, FrontierStats, SymExecState, Candidate, hard caps.
  - select.rs: seed scoring (favored > productive > shorter), deepest
    unseen-frontier picker, attempt bookkeeping.
  - mutate.rs: ABI-aware Redqueen-style calldata rewrites for scalar args
    (uintN/intN/bool/address/bytesN). Skips dynamic types in v1.
  - mod.rs: SymBackend trait + HeuristicAbiRewrite v1 backend +
    run_symexec_assist top-level loop. Trait stays in place so v2 can swap in
    z3/hevm/halmos without changing the loop.

- WorkerCorpus helpers: is_master, symexec_seed_pool, history_map_snapshot,
  master_sync_dir, symexec_validate. The validator clones the executor and
  history map and only reports new edges; it never mutates the live history
  map, so the next calibrate() picks up the persisted file in the normal way
  without poisoning the corpus.

- Config: FuzzCorpusConfig.symexec_assist (bool, default false) +
  symexec_assist_interval (u32, default 200) + symexec_assist_active() guard
  (requires coverage-guided + EVM edge coverage; sancov-edges disables it).

- Wiring:
  - executors/fuzz/mod.rs: master worker only, periodic call after each sync,
    stateful = false.
  - executors/invariant/mod.rs: single worker, periodic call at the top of the
    run loop, stateful = true (commits prefix txs during replay/validation,
    resolves the final tx's ABI dynamically via FuzzRunIdentifiedContracts.

- Inspector plumbing: branch_trace propagates through InspectorStack ->
  InspectorData -> RawCallResult.branch_trace (mirrors the existing
  edge_coverage path).

Validation gate ensures only candidates that produce a real new EVM edge are
persisted to <corpus_dir>/worker0/sync/, where the existing corpus protocol
distributes them to other workers.

Hard CPU budget per cycle: 1 seed, 1 frontier, <=8 candidates, max 3 attempts
per frontier per campaign.

Tests:
- forge cli: symexec_assist_solves_equality_guard (stateless fuzz) — handler
  with require(x == MAGIC) where MAGIC is a 32-byte distinctive value;
  asserts the corpus directory contains the magic bytes after the run.
- forge cli: symexec_assist_solves_equality_guard_invariant (stateful
  invariant) — same handler exposed via targetContract; trivial invariant;
  same structural corpus check.

All existing tests still pass:
  forge cli fuzz tests: 16 passed (incl. new regression)
  forge cli invariant tests: 68 passed (incl. new regression)
  foundry-evm lib tests: 21 passed
  foundry-config lib tests: 154 passed

Future extensions kept open by the SymBackend trait:
- Z3PathFlip backend (real SMT)
- ExternalHevm / ExternalHalmos backends
- Mutating the final-tx sender for access-control branches
EOF
)

Amp-Thread-ID: https://ampcode.com/threads/T-019e2bc9-ece8-718f-9279-971e3e982bec
Co-authored-by: Amp <amp@ampcode.com>

Author: figtracer

crates/config/src/fuzz.rs

@@ -135,6 +135,18 @@ pub struct FuzzCorpusConfig {
     /// Whether to capture comparison operands from sancov-instrumented crates
     /// and inject them into the fuzz dictionary. Independent of `sancov_edges`.
     pub sancov_trace_cmp: bool,
+    /// Whether to enable the symbolic-assist worker. When set, the master
+    /// fuzz worker periodically replays a corpus seed under a branch-trace
+    /// inspector, proposes ABI-aware calldata mutations that flip an
+    /// uncovered branch, validates them through the normal coverage gate,
+    /// and writes accepted candidates into its `sync/` directory so the
+    /// existing corpus protocol distributes them.
+    /// Requires `corpus_dir` to be set and EVM edge coverage to be enabled
+    /// (i.e. `sancov_edges` off).
+    pub symexec_assist: bool,
+    /// Number of fuzz runs between symbolic-assist cycles on the master
+    /// worker. Ignored when `symexec_assist` is `false`.
+    pub symexec_assist_interval: u32,
 }
 
 impl FuzzCorpusConfig {
@@ -178,6 +190,13 @@ impl FuzzCorpusConfig {
     pub const fn is_coverage_guided(&self) -> bool {
         self.corpus_dir.is_some()
     }
+
+    /// Whether the symbolic-assist worker should run. v1 only supports the
+    /// EVM edge-coverage signal, so we require coverage-guided mode and
+    /// disable assist when sancov edges are taking over.
+    pub const fn symexec_assist_active(&self) -> bool {
+        self.symexec_assist && self.is_coverage_guided() && !self.sancov_edges
+    }
 }
 
 impl Default for FuzzCorpusConfig {
@@ -190,6 +209,8 @@ impl Default for FuzzCorpusConfig {
             show_edge_coverage: false,
             sancov_edges: false,
             sancov_trace_cmp: false,
+            symexec_assist: false,
+            symexec_assist_interval: 200,
         }
     }
 }

crates/evm/evm/src/executors/corpus.rs

@@ -1116,6 +1116,88 @@ impl WorkerCorpus {
         Ok(())
     }
 
+    // -- Symbolic-assist helpers ------------------------------------------
+    //
+    // These accessors are used by `crate::executors::symexec::run_symexec_assist`
+    // to drive the master worker's symbolic-assist cycle without exposing
+    // `CorpusEntry` internals to the rest of the crate.
+
+    /// Whether this is the master worker (the only one allowed to drive
+    /// symbolic assist in v1).
+    pub const fn is_master(&self) -> bool {
+        self.id == 0
+    }
+
+    /// Snapshot a small candidate pool of seeds for symbolic-assist seed
+    /// scoring. Returns at most `MAX` entries (kept tiny so scoring stays
+    /// cheap).
+    pub fn symexec_seed_pool(&self) -> Vec<crate::executors::symexec::SeedSnapshot> {
+        const MAX: usize = 16;
+        self.in_memory_corpus
+            .iter()
+            .rev()
+            .take(MAX)
+            .map(|e| crate::executors::symexec::SeedSnapshot {
+                uuid: e.uuid,
+                tx_seq: e.tx_seq.clone(),
+                is_favored: e.is_favored,
+                new_finds_produced: e.new_finds_produced,
+            })
+            .collect()
+    }
+
+    /// Returns a copy of the current EVM history map. Used by the symbolic
+    /// worker to detect frontier (currently-unseen) edges without holding
+    /// the corpus mutably for the duration of replay.
+    pub fn history_map_snapshot(&self) -> Vec<u8> {
+        self.history_map.clone()
+    }
+
+    /// Path to the master worker's `sync/` directory. The symbolic-assist
+    /// worker writes accepted candidates here so the next `sync()` cycle
+    /// imports them.
+    pub fn master_sync_dir(&self) -> Option<PathBuf> {
+        self.config.corpus_dir.as_ref().map(|d| d.join(format!("{WORKER}0")).join(SYNC_DIR))
+    }
+
+    /// Validate a candidate sequence produced by the symbolic-assist
+    /// worker: re-run it through a clone of `executor` and report whether
+    /// it produced at least one previously-unseen EVM edge against a
+    /// snapshot of the history map. Does *not* mutate `self.history_map`
+    /// — the next `calibrate()` call will fold in the persisted file's
+    /// coverage in the normal way.
+    ///
+    /// `stateful` mirrors `WorkerCorpus::new`'s replay behavior: when
+    /// `true`, intermediate txs are committed so later txs see the prefix
+    /// state (invariant tests). When `false`, each tx runs against the
+    /// post-`setUp` baseline (stateless fuzz).
+    pub fn symexec_validate<FEN: FoundryEvmNetwork>(
+        &self,
+        executor: &Executor<FEN>,
+        candidate: &[BasicTxDetails],
+        stateful: bool,
+    ) -> Result<bool> {
+        if !self.config.collect_evm_edge_coverage() {
+            return Ok(false);
+        }
+        let mut executor = executor.clone();
+        let mut history = self.history_map.clone();
+        let mut sancov_history = self.sancov_history_map.clone();
+        let mut produced_new = false;
+        for tx in candidate {
+            let mut result = execute_tx(&mut executor, tx)?;
+            let (new_coverage, _is_edge) =
+                result.merge_all_coverage(&mut history, &mut sancov_history);
+            if new_coverage {
+                produced_new = true;
+            }
+            if stateful {
+                executor.commit(&mut result);
+            }
+        }
+        Ok(produced_new)
+    }
+
     /// Helper to check if a tx can be replayed.
     fn can_replay_tx(
         tx: &BasicTxDetails,

crates/evm/evm/src/executors/fuzz/mod.rs

@@ -1,6 +1,7 @@
 use crate::executors::{
     DURATION_BETWEEN_METRICS_REPORT, EarlyExit, Executor, FuzzTestTimer, RawCallResult,
     corpus::{GlobalCorpusMetrics, WorkerCorpus},
+    symexec::{self, SymExecState},
 };
 use alloy_dyn_abi::JsonAbiExt;
 use alloy_json_abi::Function;
@@ -499,6 +500,18 @@ impl<FEN: FoundryEvmNetwork> FuzzedExecutor<FEN> {
         let sync_threshold = SYNC_INTERVAL + sync_offset;
         let mut runs_since_sync = sync_threshold; // Always sync at the start.
         let mut last_metrics_report = Instant::now();
+
+        // Symbolic-assist state — only initialised on the master worker
+        // (`worker_id == 0`). The master periodically replays a corpus seed
+        // under a branch-trace inspector, proposes ABI-aware mutations
+        // that flip an unseen branch, validates them via normal coverage,
+        // and writes accepted candidates into its own `sync/` directory so
+        // the existing corpus protocol distributes them.
+        let symexec_active =
+            worker_id == 0 && self.config.corpus.symexec_assist_active();
+        let symexec_interval = self.config.corpus.symexec_assist_interval.max(1);
+        let mut runs_since_symexec: u32 = 0;
+        let mut symexec_state = SymExecState::default();
         // Continue while:
         // 1. Global state allows (not timed out, not at global limit, no failure found)
         // 2. Worker hasn't reached its specific run limit
@@ -540,6 +553,38 @@ impl<FEN: FoundryEvmNetwork> FuzzedExecutor<FEN> {
                     runs_since_sync = 0;
                 }
 
+                if symexec_active {
+                    runs_since_symexec += 1;
+                    if runs_since_symexec >= symexec_interval {
+                        let timer = Instant::now();
+                        match symexec::run_symexec_assist(
+                            &mut corpus,
+                            &executor,
+                            Some(func),
+                            None,
+                            &mut symexec_state,
+                            /* stateful */ false,
+                        ) {
+                            Ok(n) if n > 0 => {
+                                trace!(
+                                    target: "corpus",
+                                    "symexec assist accepted {n} candidates in {:?}",
+                                    timer.elapsed()
+                                );
+                            }
+                            Ok(_) => {}
+                            Err(err) => {
+                                debug!(
+                                    target: "corpus",
+                                    %err,
+                                    "symexec assist cycle errored"
+                                );
+                            }
+                        }
+                        runs_since_symexec = 0;
+                    }
+                }
+
                 let fuzz_run = self.config.run.unwrap_or(worker.runs + 1);
                 if let Some(cheats) = executor.inspector_mut().cheatcodes.as_mut()
                     && let Some(seed) = self.config.seed

crates/evm/evm/src/executors/invariant/mod.rs

@@ -1,7 +1,9 @@
 use crate::{
     executors::{
         DURATION_BETWEEN_METRICS_REPORT, EarlyExit, EvmError, Executor, FuzzTestTimer,
-        RawCallResult, corpus::WorkerCorpus,
+        RawCallResult,
+        corpus::WorkerCorpus,
+        symexec::{self, SymExecState},
     },
     inspectors::Fuzzer,
 };
@@ -462,7 +464,47 @@ impl<'a, FEN: FoundryEvmNetwork> InvariantExecutor<'a, FEN> {
         // Invariant runs with edge coverage if corpus dir is set or showing edge coverage.
         let edge_coverage_enabled = self.config.corpus.collect_edge_coverage();
 
+        // Symbolic-assist state for invariant tests. The invariant runner
+        // is single-worker, so the assist always runs (when enabled) on
+        // the master corpus.
+        let symexec_active = self.config.corpus.symexec_assist_active();
+        let symexec_interval = self.config.corpus.symexec_assist_interval.max(1);
+        let mut runs_since_symexec: u32 = 0;
+        let mut symexec_state = SymExecState::default();
+
         'stop: while continue_campaign(runs) {
+            if symexec_active {
+                runs_since_symexec += 1;
+                if runs_since_symexec >= symexec_interval {
+                    let timer = Instant::now();
+                    match symexec::run_symexec_assist(
+                        &mut corpus_manager,
+                        &self.executor,
+                        None,
+                        Some(&invariant_test.targeted_contracts),
+                        &mut symexec_state,
+                        /* stateful */ true,
+                    ) {
+                        Ok(n) if n > 0 => {
+                            trace!(
+                                target: "corpus",
+                                "symexec assist accepted {n} candidates in {:?}",
+                                timer.elapsed()
+                            );
+                        }
+                        Ok(_) => {}
+                        Err(err) => {
+                            debug!(
+                                target: "corpus",
+                                %err,
+                                "symexec assist cycle errored"
+                            );
+                        }
+                    }
+                    runs_since_symexec = 0;
+                }
+            }
+
             // Per-run failure count snapshot used to gate `afterInvariant` below.
             let failures_before_run = invariant_test.test_data.failures.errors.len();
 

crates/evm/evm/src/executors/mod.rs

@@ -63,6 +63,7 @@ pub use invariant::InvariantExecutor;
 
 mod corpus;
 mod sancov;
+pub mod symexec;
 mod trace;
 
 pub use trace::TracingExecutor;
@@ -961,6 +962,8 @@ pub struct RawCallResult<FEN: FoundryEvmNetwork = EthEvmNetwork> {
     pub line_coverage: Option<HitMaps>,
     /// The edge coverage info collected during the call
     pub edge_coverage: Option<Vec<u8>>,
+    /// Branch observations collected by the symbolic-assist worker.
+    pub branch_trace: Option<crate::inspectors::BranchTrace>,
     /// Sancov edge coverage from instrumented native Rust crates (e.g. precompiles).
     /// Tracked separately from EVM edge coverage to avoid ID-space collisions.
     pub sancov_coverage: Option<Vec<u8>>,
@@ -998,6 +1001,7 @@ impl<FEN: FoundryEvmNetwork> Default for RawCallResult<FEN> {
             traces: None,
             line_coverage: None,
             edge_coverage: None,
+            branch_trace: None,
             sancov_coverage: None,
             sancov_cmp_values: None,
             transactions: None,
@@ -1217,6 +1221,7 @@ fn convert_executed_result<FEN: FoundryEvmNetwork>(
         traces,
         line_coverage,
         edge_coverage,
+        branch_trace,
         cheatcodes,
         chisel_state,
         reverter,
@@ -1244,6 +1249,7 @@ fn convert_executed_result<FEN: FoundryEvmNetwork>(
         traces,
         line_coverage,
         edge_coverage,
+        branch_trace,
         sancov_coverage: None,
         sancov_cmp_values: None,
         transactions,