Add reactive event handler runtime

CHANGELOG.md

@@ -123,6 +123,31 @@ pre-release development phases (see [`docs/ROADMAP.md`](docs/ROADMAP.md)).
     chain truth (correct **and** alarm) via the new `EvmCache::reconcile_slots`. A
     thin async `drive`/`LogSource` convenience layers the synchronous core over a
     stream. Generic core.
+- **Reactive runtime** (`reactive` module, default-enabled) — a provider-neutral
+  handler pipeline for logs, block notifications, and pending transaction
+  signals. `ReactiveHandler`s are pure synchronous functions over
+  `ReactiveInput` + `ReactiveContext` + `StateView`; they emit `StateUpdate`s,
+  invalidations, resync requests, speculative requests, and hook signals. The
+  runtime deduplicates inputs by `InputRef`, orders canonical logs by
+  `(block_number, transaction_index, log_index)`, routes by `ReactiveInterest`
+  with Alloy `Filter`s and local matchers, validates pending inputs so they
+  cannot mutate canonical cache state, detects conflicting absolute writes for a
+  single input, applies canonical mutations through `EvmCache::apply_updates`,
+  and dispatches `ReactiveReport`s to hooks after mutation phases.
+  `ReactiveRegistry` exposes consolidated Alloy log filters for provider
+  subscription setup and exact local log routing with optional route keys.
+  Includes a provider-agnostic `EventSubscriber` trait, an `AlloySubscriber`
+  scaffold for future live transport work, and an adapter from legacy
+  `EventDecoder`s to reactive handlers. Generic core.
+- **Reactive storage resync execution** — `ReactiveRuntime::ingest_batch_with_resync`
+  preserves the direct-effect behavior of `ingest_batch`, then executes surfaced
+  storage resync requests through `EvmCache`'s provider-neutral
+  `StorageBatchFetchFn`, applies successful values as `StateUpdate::slot`
+  updates, and reports requested targets, applied updates, the resulting
+  `StateDiff`, and per-target failures in `ResyncReport`. `ResyncFailureKind`
+  gives downstream retry policy and metrics a stable failure classification.
+  Account-field resyncs remain explicitly unsupported until a provider-neutral
+  account fetch callback exists. Generic core.
 - **`StateUpdate::SlotMasked`** (`state_update`, Phase 4) — a cold-aware
   read-modify-write *masked* slot write (`new = (old & !mask) | (value & mask)`)
   with the `StateUpdate::slot_masked` constructor, so a pure decoder can update

Cargo.toml

@@ -15,6 +15,10 @@ documentation = "https://docs.rs/evm-fork-cache"
 # ancestor-directory workspace and gives it its own Cargo.lock.
 [workspace]
 
+[features]
+default = ["reactive"]
+reactive = []
+
 [dependencies]
 alloy-consensus = "1.1.2"
 alloy-contract = "1.0.38"

README.md

@@ -38,10 +38,10 @@ around three capabilities that target exactly this workload:
 
 > **Maturity.** This crate is **pre-1.0** and under active development against a
 > [phased roadmap](docs/ROADMAP.md). Capabilities (1) and (3) above are
-> implemented today. Capability (2) has the targeted writer primitives and the
-> event-to-state reader pipeline; a production WebSocket transport remains
-> consumer-provided. The public API still changes between minor versions — see
-> [Stability](#stability).
+> implemented today. Capability (2) has the targeted writer primitives, the
+> event-to-state reader pipeline, and a default-enabled reactive handler runtime;
+> live network subscription driving remains consumer-provided. The public API
+> still changes between minor versions — see [Stability](#stability).
 
 ## What it provides today
 
@@ -60,6 +60,18 @@ around three capabilities that target exactly this workload:
   against RPC. The crate ships the generic driver, the ERC-20 `Transfer` decoder,
   and in-memory examples; production WebSocket subscription/reorg wiring and
   protocol-specific decoders stay with the consumer or companion crates.
+- **Reactive runtime** — register pure handlers for logs, block notifications,
+  and pending transaction signals. Handlers emit `StateUpdate`s, invalidations,
+  resync requests, speculative signals, and hook signals; the runtime routes
+  inputs, deduplicates and orders canonical logs, validates pending semantics,
+  applies canonical cache mutations through `EvmCache::apply_updates`, and
+  can optionally execute storage resync requests through the cache's
+  provider-neutral storage batch fetcher before dispatching reports to hooks. The
+  `ReactiveRegistry` exposes consolidated Alloy log filters for provider
+  subscription setup and exact local log routing with optional route keys. The
+  provider-agnostic `EventSubscriber` trait and `AlloySubscriber` scaffold are
+  included; live Alloy stream driving is intentionally left to a future transport
+  layer.
 - **ERC20 helpers** — balances, allowances, decimals, and controlled balance
   mutation (including automatic balance-slot discovery) for simulations.
 - **Transfer-inspector simulation** that reports per-token balance deltas

src/lib.rs

@@ -54,6 +54,10 @@
 //!   `StateView` / `DecoderRegistry` decode an on-chain `Log` into `StateUpdate`s,
 //!   and `EventPipeline` ingests, reorg-purges, and reconciles a block's logs.
 //!   Ships an ERC-20 `Transfer` decoder plus traits for external decoders.
+//! - `reactive` — default-enabled provider-neutral handler runtime for logs,
+//!   blocks, and pending transaction signals. Pure handlers emit `StateUpdate`s,
+//!   invalidations, resync requests, speculative signals, and hooks; the runtime
+//!   validates and applies canonical cache mutations.
 //! - [`inspector`] — an [`Inspector`](revm::Inspector) that captures ERC20
 //!   `Transfer` events to reconstruct balance deltas from a simulation.
 //! - [`multicall`] — batched read-only calls through Multicall3.
@@ -110,6 +114,8 @@ pub mod freshness;
 pub mod inspector;
 pub mod multicall;
 pub mod prefetch_registry;
+#[cfg(feature = "reactive")]
+pub mod reactive;
 pub mod state_update;
 
 pub use access_set::StorageAccessList;