evm_fork_cache/reactive/

mod.rs

//! Protocol-neutral reactive runtime for cache state effects.
//!
//! The reactive runtime generalizes the log-only [`events`](crate::events)
//! pipeline into a handler pipeline that can ingest logs, block notifications,
//! and pending transaction signals. Handlers remain pure synchronous functions:
//! they read through [`StateView`], return structured
//! [`ReactiveEffect`] values, and let the runtime validate and commit cache
//! mutations through [`StateUpdate`].
//!
//! This module intentionally contains no protocol, AMM, strategy, signing, or
//! transaction-submission concepts. Downstream crates can layer those domains on
//! top by implementing [`ReactiveHandler`] and [`ReactiveHook`].

use std::{
    any::Any,
    borrow::Cow,
    collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque},
    fmt,
    future::Future,
    hash::Hash,
    marker::PhantomData,
    num::NonZeroU64,
    path::PathBuf,
    pin::Pin,
    sync::{
        Arc,
        atomic::{AtomicU64, Ordering},
    },
    time::Duration,
};

use alloy_consensus::{BlockHeader as _, Transaction as _};
use alloy_eips::{BlockId, BlockNumberOrTag};
use alloy_network::{
    Ethereum, Network,
    primitives::{
        BlockResponse as _, HeaderResponse as HeaderResponseTrait,
        TransactionResponse as TransactionResponseTrait,
    },
};
use alloy_primitives::{Address, B256, Bytes, FixedBytes, Keccak256, U256};
use alloy_provider::Provider;
use alloy_rpc_types_eth::{Filter, FilterSet, Log};
pub use alloy_transport_balancer::EndpointId;
use bincode::Options;
use futures::{StreamExt, stream};
use futures::{
    future::{Either, poll_fn, select},
    stream::BoxStream,
};

use crate::{
    cache::{
        AccountProof, BlockStateDiff, DurableCheckpointBlock, DurableCheckpointError,
        DurableCheckpointIdentity, DurableCheckpointMetadata, DurableCheckpointStore, EvmCache,
        EvmCacheStateSnapshot, LoadedDurableCheckpoint,
    },
    errors::{BlockContextError, StorageFetchResult},
    events::{EventDecoder, StateView},
    freshness::FreshnessRegistry,
    state_update::{AccountPatch, PurgeScope, StateDiff, StateUpdate},
};

/// Input accepted by the reactive runtime.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ReactiveInput<N: Network = Ethereum> {
    /// A canonical or removed EVM log, using Alloy's RPC log type.
    Log(Log),
    /// A block header response for header-oriented handlers.
    BlockHeader(N::HeaderResponse),
    /// A full block response for block handlers that need transaction bodies.
    FullBlock(N::BlockResponse),
    /// A pending transaction hash.
    PendingTxHash(B256),
    /// A full pending transaction body.
    PendingTx(N::TransactionResponse),
}

/// Context supplied with each [`ReactiveInput`].
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ReactiveContext {
    /// Chain id, when known.
    pub chain_id: Option<u64>,
    /// Where the input came from.
    pub source: InputSource,
    /// Lifecycle status of the input.
    pub chain_status: ChainStatus,
    /// Block metadata associated with the input, when known.
    pub block: Option<BlockRef>,
    /// Transaction index for log or transaction inputs.
    pub transaction_index: Option<u64>,
    /// Log index for log inputs.
    pub log_index: Option<u64>,
}

/// Minimal block identity carried through reports.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct BlockRef {
    /// Block number.
    pub number: u64,
    /// Block hash.
    pub hash: B256,
    /// Parent hash, when known.
    pub parent_hash: Option<B256>,
    /// Block timestamp, when known.
    pub timestamp: Option<u64>,
}

/// Stable provider identity attached to provider-originated input.
///
/// `generation` changes whenever a caller replaces or reconnects the concrete
/// provider session behind the same configured endpoint. Follow-up reads can
/// use this value to prefer the exact source that announced speculative state
/// without putting URLs or credentials into event payloads.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct ProviderRef {
    /// Operator-defined endpoint identity.
    pub endpoint: EndpointId,
    /// Concrete connection/session generation.
    pub generation: u64,
}

impl ProviderRef {
    /// Construct provider provenance for one connection generation.
    pub fn new(endpoint: impl Into<EndpointId>, generation: u64) -> Self {
        Self {
            endpoint: endpoint.into(),
            generation,
        }
    }
}

/// Identity of one cumulative pre-confirmed Flashblock snapshot.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct FlashblockRef {
    /// Provider session that supplied this snapshot.
    pub provider: ProviderRef,
    /// Sequencer payload id shared by every Flashblock in the full block.
    ///
    /// OP RPCs that expose only the standard pending block surface may not
    /// expose this Base-native identifier.
    pub payload_id: Option<FixedBytes<8>>,
    /// Zero-based Flashblock index, when exposed by the endpoint.
    pub index: Option<u64>,
    /// Pending block number represented by this cumulative snapshot.
    pub block_number: u64,
    /// Hash of the cumulative partial block at this snapshot.
    pub block_hash: B256,
    /// Canonical parent of the pending block, when exposed.
    pub parent_hash: Option<B256>,
    /// State root after this cumulative snapshot, when exposed.
    pub state_root: Option<B256>,
    /// Pending block timestamp, when exposed.
    pub timestamp: Option<u64>,
}

impl FlashblockRef {
    /// Convert the pre-confirmed identity into the block metadata used by
    /// ordinary log routing. The hash is explicitly a partial/pending hash and
    /// must not advance canonical coverage.
    pub const fn block_ref(&self) -> BlockRef {
        BlockRef {
            number: self.block_number,
            hash: self.block_hash,
            parent_hash: self.parent_hash,
            timestamp: self.timestamp,
        }
    }

    fn same_payload(&self, other: &Self) -> bool {
        self.provider == other.provider
            && match (self.payload_id, other.payload_id) {
                (Some(left), Some(right)) => left == right,
                _ => {
                    self.block_number == other.block_number && self.parent_hash == other.parent_hash
                }
            }
    }
}

/// Whether the subscriber may use Flashblocks for speculative delivery.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum PreconfirmationMode {
    /// Use only canonical subscription/polling behavior.
    #[default]
    Disabled,
    /// Prefer Flashblocks, but retain canonical operation when the selected
    /// chain/provider cannot establish the pre-confirmation stream.
    Preferred,
    /// Fail setup/reconnect closed unless Flashblocks can be established.
    Required,
}

/// Base-native `newFlashblocks` subscription payload.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
pub struct BaseFlashblockPayload {
    /// Block-builder payload id shared by every incremental snapshot.
    pub payload_id: FixedBytes<8>,
    /// Zero-based incremental snapshot index.
    pub index: u64,
    /// Header fields present on index zero.
    pub base: Option<BaseFlashblockBase>,
    /// Cumulative state commitments for this snapshot.
    pub diff: BaseFlashblockDiff,
    /// Supplemental block identity retained across current Base versions.
    #[serde(default)]
    pub metadata: Option<BaseFlashblockMetadata>,
}

/// Stable index-zero header subset from Base's Flashblocks wire format.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
pub struct BaseFlashblockBase {
    /// Canonical parent block hash.
    pub parent_hash: B256,
    /// Pending block number.
    #[serde(deserialize_with = "deserialize_rpc_u64")]
    pub block_number: u64,
    /// Pending block timestamp.
    #[serde(deserialize_with = "deserialize_rpc_u64")]
    pub timestamp: u64,
}

/// Stable commitment subset from Base's Flashblocks wire format.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
pub struct BaseFlashblockDiff {
    /// State root after this cumulative snapshot.
    pub state_root: B256,
    /// Partial block hash after this cumulative snapshot.
    pub block_hash: B256,
}

/// Stable metadata subset used when index-greater-than-zero payloads omit the
/// Base header object.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
pub struct BaseFlashblockMetadata {
    /// Pending block number (currently encoded as a JSON integer).
    #[serde(deserialize_with = "deserialize_rpc_u64")]
    pub block_number: u64,
}

/// Current Base/QuickNode `newFlashblocks` wire shape. The endpoint emits a
/// cumulative block-shaped snapshot for every partial block update.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct BaseFlashblockBlockPayload {
    hash: B256,
    #[serde(deserialize_with = "deserialize_rpc_u64")]
    number: u64,
    parent_hash: B256,
    state_root: B256,
    #[serde(deserialize_with = "deserialize_rpc_u64")]
    timestamp: u64,
}

/// Base has exposed both an indexed diff envelope and a cumulative
/// block-shaped envelope for `newFlashblocks`. Accept both so provider rollout
/// differences do not force callers onto separate subscriber paths.
#[derive(Clone, Debug, PartialEq, Eq, serde::Deserialize)]
#[serde(untagged)]
enum BaseFlashblockWirePayload {
    Indexed(BaseFlashblockPayload),
    Block(BaseFlashblockBlockPayload),
}

fn deserialize_rpc_u64<'de, D>(deserializer: D) -> Result<u64, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(serde::Deserialize)]
    #[serde(untagged)]
    enum RpcU64 {
        Number(u64),
        String(String),
    }

    match <RpcU64 as serde::Deserialize>::deserialize(deserializer)? {
        RpcU64::Number(number) => Ok(number),
        RpcU64::String(value) => {
            let value = value.strip_prefix("0x").unwrap_or(&value);
            u64::from_str_radix(value, 16).map_err(serde::de::Error::custom)
        }
    }
}

/// Exact chain/block identity of an RPC cache snapshot adopted as the starting
/// point for reactive event continuity.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct ReactiveCanonicalBaseline {
    /// Chain whose state the cache snapshot contains.
    pub chain_id: u64,
    /// Canonical block through which the snapshot already embodies state.
    pub block: BlockRef,
}

impl ReactiveCanonicalBaseline {
    /// Construct an exact cache snapshot baseline.
    pub const fn new(chain_id: u64, block: BlockRef) -> Self {
        Self { chain_id, block }
    }
}

/// Ordered chain-lifecycle control delivered by an event subscriber.
///
/// Controls live inside [`ReactiveInputBatch`] so they share the same delivery
/// token, durable checkpoint, and ordering guarantees as ordinary event data.
/// Reorg controls are applied in declaration order before replacement records;
/// progress, barrier, safe, and finalized controls are committed in declaration
/// order after the records. A reorg declared after a post-record control is
/// rejected because its ordering would otherwise be ambiguous.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum ChainControl {
    /// Replace the old canonical branch after `common_ancestor` with `new_tip`.
    Reorg {
        /// Last block common to the old and new canonical branches.
        common_ancestor: BlockRef,
        /// Tip of the branch that ceased to be canonical.
        old_tip: BlockRef,
        /// Tip of the newly canonical branch known by the source.
        new_tip: BlockRef,
    },
    /// Update the source's safe head.
    Safe(BlockRef),
    /// Update the source's finalized head.
    Finalized(BlockRef),
    /// Advance authoritative canonical coverage without fabricating a full header.
    ///
    /// Indexers that only know compact block identity should emit this control.
    /// It never runs block handlers. The runtime exact-hash pins provider reads
    /// and installs known `NUMBER`/timestamp values, but clears unproven
    /// header-only environment fields such as base fee and beneficiary.
    CanonicalProgress(BlockRef),
    /// Ordered cutover or synchronization fence.
    Barrier {
        /// Subscriber-defined opaque barrier identity.
        id: Vec<u8>,
        /// Highest canonical event block included before the fence, if known.
        block: Option<BlockRef>,
    },
}

/// Provider-neutral snapshot consumed by [`validate_canonical_sequence`].
///
/// Composite subscribers can persist this small chain-state view beside their
/// own delivery checkpoint and validate a complete delivery envelope before it
/// reaches a [`ReactiveRuntime`]. The retained history may be sparse (blocks
/// without matching events need not be present), but it must contain at most
/// one compatible identity per height. Its oldest entry is also the durable
/// rollback horizon: an unretained explicit ancestor is accepted only when that
/// oldest entry is at or below the ancestor. This type carries no cache data,
/// event payloads, handler state, or transport-specific cursor.
///
/// The serde representation is a convenience for caller-owned persistence; it
/// is not a versioned wire or checkpoint format. Durable protocols should wrap
/// it in their own versioned envelope and define migrations before upgrading
/// this pre-1.0 crate. External callers also own retention: successful
/// validation appends canonical identities but does not silently discard the
/// rollback proof window. Bound it with [`Self::retain_recent_history`] after
/// committing the matching source cursor/ACK.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct CanonicalSequenceState {
    retained_canonical_history: Vec<BlockRef>,
    coverage_head: Option<BlockRef>,
    safe_head: Option<BlockRef>,
    finalized_head: Option<BlockRef>,
}

impl CanonicalSequenceState {
    /// Construct a validation snapshot from retained canonical metadata.
    ///
    /// Construction does not validate ordering, adjacency, coverage, or
    /// finality invariants. Call [`Self::validate`] before installing decoded or
    /// externally assembled state.
    pub fn new(
        retained_canonical_history: Vec<BlockRef>,
        coverage_head: Option<BlockRef>,
        safe_head: Option<BlockRef>,
        finalized_head: Option<BlockRef>,
    ) -> Self {
        Self {
            retained_canonical_history,
            coverage_head,
            safe_head,
            finalized_head,
        }
    }

    /// Sparse retained canonical history in ascending processing order.
    pub fn retained_canonical_history(&self) -> &[BlockRef] {
        &self.retained_canonical_history
    }

    /// Highest canonical identity covered by this state, when known.
    pub const fn coverage_head(&self) -> Option<&BlockRef> {
        self.coverage_head.as_ref()
    }

    /// Latest safe head accepted by the validator, when known.
    pub const fn safe_head(&self) -> Option<&BlockRef> {
        self.safe_head.as_ref()
    }

    /// Latest finalized head accepted by the validator, when known.
    pub const fn finalized_head(&self) -> Option<&BlockRef> {
        self.finalized_head.as_ref()
    }

    /// Retain at most the newest `max_entries` canonical history identities.
    ///
    /// Coverage and safe/finalized heads are unchanged. The oldest retained
    /// identity defines how far strict validation can prove a complete
    /// rollback, so choose a bound at least as large as the deployment's
    /// supported reorg depth and trim only after atomically committing the
    /// corresponding validated state and source cursor. `0` intentionally
    /// produces a coverage-only snapshot.
    pub fn retain_recent_history(&mut self, max_entries: usize) {
        let remove = self
            .retained_canonical_history
            .len()
            .saturating_sub(max_entries);
        self.retained_canonical_history.drain(..remove);
    }

    /// Validate a decoded/checkpointed snapshot before installing it.
    ///
    /// This rejects out-of-order or conflicting retained identities,
    /// broken adjacent parent links, retained history without coverage,
    /// incompatible coverage/finality aliases, hash reuse across heights,
    /// known parent hashes at non-adjacent heights, finality beyond coverage,
    /// and a finalized head beyond or conflicting with the safe head.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveError`] when any retained identity, parent link,
    /// coverage alias, or safe/finalized relationship violates the canonical
    /// snapshot invariants described above.
    pub fn validate(&self) -> Result<(), ReactiveError> {
        validate_canonical_sequence_snapshot(self)
    }
}

/// Cache-free canonical transition proven by [`validate_canonical_sequence`].
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum CanonicalSequenceMutation {
    /// Rewind the listed retained identities and continue from `common_ancestor`.
    Rewind {
        /// Surviving canonical anchor, when one is retained or authenticated.
        /// `None` is a transient same-envelope state: callers must stage the
        /// complete validation atomically and may checkpoint only the returned
        /// `next_state`, after a later canonical mutation installs the proven
        /// replacement.
        common_ancestor: Option<BlockRef>,
        /// Exact retained identities removed by the transition.
        dropped: Vec<BlockRef>,
    },
    /// Accept or enrich one canonical identity.
    Canonical(BlockRef),
    /// Accept a safe-head update with metadata resolved against prior state.
    Safe(BlockRef),
    /// Accept a finalized-head update with metadata resolved against prior state.
    Finalized(BlockRef),
}

/// Successful result of provider-neutral canonical envelope validation.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CanonicalSequenceValidation {
    pre_record_state: CanonicalSequenceState,
    next_state: CanonicalSequenceState,
    mutations: Vec<CanonicalSequenceMutation>,
    normalized_chain_controls: Vec<ChainControl>,
}

impl CanonicalSequenceValidation {
    /// State after pre-record explicit reorg controls and before event records.
    pub const fn pre_record_state(&self) -> &CanonicalSequenceState {
        &self.pre_record_state
    }

    /// Fully validated state after records and post-record controls.
    pub const fn next_state(&self) -> &CanonicalSequenceState {
        &self.next_state
    }

    /// Ordered cache-free canonical mutations proven by this envelope.
    pub fn mutations(&self) -> &[CanonicalSequenceMutation] {
        &self.mutations
    }

    /// Controls safe to forward after composite overlap normalization.
    ///
    /// Ordinary validation retains the original controls. See
    /// [`normalize_and_validate_canonical_sequence`] for the mode that removes
    /// compatible stale progress and converts a stale blockful barrier into the
    /// same barrier identity without a block assertion. Equal-height controls
    /// that add previously absent parent/timestamp metadata remain present;
    /// older compatible enrichment is intentionally not applied because the
    /// corresponding regressive control is not forwarded to the runtime.
    pub fn normalized_chain_controls(&self) -> &[ChainControl] {
        &self.normalized_chain_controls
    }
}

/// Lifecycle status for an input.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum ChainStatus {
    /// The input is mempool-only and must not mutate canonical cache state.
    Pending,
    /// The input is ordered into an ephemeral sequencer-built Flashblock.
    ///
    /// Handlers may update the runtime's speculative overlay for this status,
    /// but the update never advances canonical coverage or durable journals.
    Preconfirmed {
        /// Exact cumulative pre-confirmation snapshot observed by the source.
        flashblock: FlashblockRef,
    },
    /// The input is included in a block with a confirmation count.
    Included {
        /// Included block.
        block: BlockRef,
        /// Confirmation count.
        confirmations: u64,
    },
    /// The input is in the chain's safe head.
    Safe {
        /// Safe block.
        block: BlockRef,
    },
    /// The input is in the finalized head.
    Finalized {
        /// Finalized block.
        block: BlockRef,
    },
    /// The input was dropped by a reorg.
    Reorged {
        /// Block the input was dropped from.
        dropped_from: BlockRef,
    },
}

/// Source of an input batch.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum InputSource {
    /// Caller-supplied batch.
    Batch,
    /// Live subscription stream.
    Subscription,
    /// Polling subscriber.
    Poll,
    /// Historical backfill.
    Backfill,
    /// Sequencer pre-confirmation / Flashblocks surface.
    Flashblocks,
    /// Test or synthetic input.
    Synthetic,
}

/// Stable identity used for input deduplication and reports.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum InputRef {
    /// Stable log identity.
    Log {
        /// Chain id, when known.
        chain_id: Option<u64>,
        /// Block hash containing the log.
        block_hash: B256,
        /// Transaction hash that emitted the log.
        transaction_hash: B256,
        /// Log index within the block.
        log_index: u64,
    },
    /// Stable pending transaction identity.
    PendingTx {
        /// Chain id, when known.
        chain_id: Option<u64>,
        /// Transaction hash.
        hash: B256,
    },
    /// Stable block identity.
    Block {
        /// Chain id, when known.
        chain_id: Option<u64>,
        /// Block hash.
        hash: B256,
        /// Block number.
        number: u64,
    },
}

/// Representation and lifecycle class retained alongside an [`InputRef`].
///
/// `InputRef` identifies the underlying chain object. This discriminator keeps
/// distinct handler inputs from collapsing merely because they commit to the
/// same object: a header and full block, a pending hash and hydrated body, and
/// canonical versus reorg-signalling log delivery are independently routable.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum ReactiveInputKind {
    /// Canonical log data.
    CanonicalLog,
    /// Removed or otherwise reorg-signalling log data.
    ReorgSignalLog,
    /// Header-only block representation.
    BlockHeader,
    /// Full block representation.
    FullBlock,
    /// Hash-only pending transaction representation.
    PendingTxHash,
    /// Hydrated pending transaction representation.
    PendingTx,
}

/// Validated, representation-aware identity for one reactive input.
///
/// Composite subscribers can use this as a dedupe key without conflating
/// independently routable representations. When a key repeats, use
/// [`ReactiveInputRecord::same_deduplicable_payload`] to distinguish a true
/// provider overlap from a conflicting payload.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct ReactiveInputIdentity {
    input_ref: InputRef,
    kind: ReactiveInputKind,
}

impl ReactiveInputIdentity {
    /// Validate and construct an identity from explicit wire/codec parts.
    ///
    /// `InputRef` identifies the underlying object, while `kind` identifies its
    /// representation/lifecycle. Only log kinds may pair with [`InputRef::Log`],
    /// block representations with [`InputRef::Block`], and pending-transaction
    /// representations with [`InputRef::PendingTx`]. This constructor lets
    /// external codecs rebuild the otherwise-private invariant without serde or
    /// layout-dependent decoding.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveInputIdentityError`] when `input_ref` does not belong
    /// to the supplied representation `kind`.
    pub fn try_from_parts(
        input_ref: InputRef,
        kind: ReactiveInputKind,
    ) -> Result<Self, ReactiveInputIdentityError> {
        let compatible = matches!(
            (input_ref, kind),
            (
                InputRef::Log { .. },
                ReactiveInputKind::CanonicalLog | ReactiveInputKind::ReorgSignalLog
            ) | (
                InputRef::Block { .. },
                ReactiveInputKind::BlockHeader | ReactiveInputKind::FullBlock
            ) | (
                InputRef::PendingTx { .. },
                ReactiveInputKind::PendingTxHash | ReactiveInputKind::PendingTx
            )
        );
        if !compatible {
            return Err(ReactiveInputIdentityError { input_ref, kind });
        }
        Ok(Self { input_ref, kind })
    }

    /// Underlying stable chain-object reference.
    pub const fn input_ref(&self) -> InputRef {
        self.input_ref
    }

    /// Exact handler-input representation and lifecycle class.
    pub const fn kind(&self) -> ReactiveInputKind {
        self.kind
    }
}

/// An explicit [`InputRef`] and [`ReactiveInputKind`] describe incompatible
/// object/representation classes.
#[derive(Clone, Copy, Debug, thiserror::Error, PartialEq, Eq)]
#[error("reactive input kind {kind:?} is incompatible with input reference {input_ref:?}")]
pub struct ReactiveInputIdentityError {
    input_ref: InputRef,
    kind: ReactiveInputKind,
}

impl ReactiveInputIdentityError {
    /// Rejected stable object reference.
    pub const fn input_ref(&self) -> InputRef {
        self.input_ref
    }

    /// Rejected representation/lifecycle kind.
    pub const fn kind(&self) -> ReactiveInputKind {
        self.kind
    }
}

/// Reliability of state effects emitted by a handler.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum StateEffectQuality {
    /// Effects are exact from the input alone.
    ExactFromInput,
    /// Effects were applied, but follow-up resync is pending.
    AppliedWithPendingResync,
    /// Effects came from authoritative resync.
    ResyncedAuthoritatively,
    /// State requires repair before it should be trusted.
    RequiresRepair,
    /// No canonical state effect was emitted.
    NoStateEffect,
}

/// Identifier for a reactive handler.
#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize)]
pub struct HandlerId(String);

impl HandlerId {
    /// Create a non-empty handler id.
    ///
    /// # Panics
    ///
    /// Panics when `id` is empty. Use [`try_new`](Self::try_new) for untrusted
    /// configuration or wire input.
    pub fn new(id: impl Into<String>) -> Self {
        Self::try_new(id).expect("handler id must not be empty")
    }

    /// Validate and create a handler id from untrusted input.
    ///
    /// # Errors
    ///
    /// Returns [`HandlerIdError`] when `id` is empty. The empty identity is
    /// reserved for canonical/global protocol scope.
    pub fn try_new(id: impl Into<String>) -> Result<Self, HandlerIdError> {
        let id = id.into();
        if id.is_empty() {
            return Err(HandlerIdError);
        }
        Ok(Self(id))
    }

    /// Return the id as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl<'de> serde::Deserialize<'de> for HandlerId {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let id = <String as serde::Deserialize>::deserialize(deserializer)?;
        Self::try_new(id).map_err(serde::de::Error::custom)
    }
}

/// An empty handler identity cannot be represented portably across subscriber
/// protocols because the empty owner is reserved for canonical/global scope.
#[derive(Clone, Copy, Debug, thiserror::Error, PartialEq, Eq)]
#[error("handler id must not be empty")]
pub struct HandlerIdError;

impl fmt::Display for HandlerId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

/// Lightweight report label.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ReportTag {
    /// Label key.
    pub key: String,
    /// Label value.
    pub value: String,
}

impl ReportTag {
    /// Create a report tag.
    pub fn new(key: impl Into<String>, value: impl Into<String>) -> Self {
        Self {
            key: key.into(),
            value: value.into(),
        }
    }
}

/// Domain-neutral hook signal emitted by a handler.
#[derive(Clone)]
pub struct HookSignal {
    /// Signal namespace owned by the caller.
    pub namespace: Cow<'static, str>,
    /// Signal kind within the namespace.
    pub kind: Cow<'static, str>,
    /// Additional labels for routing or observability.
    pub labels: Vec<ReportTag>,
    /// Optional in-process typed payload.
    pub payload: Option<Arc<dyn Any + Send + Sync>>,
}

impl fmt::Debug for HookSignal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("HookSignal")
            .field("namespace", &self.namespace)
            .field("kind", &self.kind)
            .field("labels", &self.labels)
            .field("payload", &self.payload.as_ref().map(|_| "<payload>"))
            .finish()
    }
}

/// Effect emitted by a [`ReactiveHandler`].
#[derive(Clone, Debug)]
pub enum ReactiveEffect {
    /// Canonical cache mutation applied through [`EvmCache::apply_updates`].
    StateUpdate(StateUpdate),
    /// Request for authoritative state repair.
    Resync(ResyncRequest),
    /// Rich invalidation request lowered to [`StateUpdate::Purge`].
    Invalidate(InvalidationRequest),
    /// Hook signal dispatched after committed mutation phases.
    Hook(HookSignal),
    /// Speculative signal for mempool or downstream work.
    Speculative(SpeculativeRequest),
}

/// Handler output for a single input.
#[derive(Clone, Debug)]
pub struct HandlerOutcome {
    /// Effects emitted by the handler.
    pub effects: Vec<ReactiveEffect>,
    /// Reliability of emitted state effects.
    pub quality: StateEffectQuality,
    /// Labels copied into reports.
    pub tags: Vec<ReportTag>,
}

impl HandlerOutcome {
    /// Construct an empty outcome with the supplied quality.
    pub fn empty(quality: StateEffectQuality) -> Self {
        Self {
            effects: Vec::new(),
            quality,
            tags: Vec::new(),
        }
    }
}

/// One input and its execution context.
#[derive(Clone, Debug)]
pub struct ReactiveInputRecord<N: Network = Ethereum> {
    /// Input value.
    pub input: ReactiveInput<N>,
    /// Input context.
    pub context: ReactiveContext,
    /// Provider session that originated this input, when it came from a
    /// concrete provider rather than a synthetic or aggregate source.
    pub provider: Option<ProviderRef>,
}

impl<N: Network> ReactiveInputRecord<N> {
    /// Create an input record.
    pub fn new(input: ReactiveInput<N>, context: ReactiveContext) -> Self {
        Self {
            input,
            context,
            provider: None,
        }
    }

    /// Attach provider provenance used to route follow-up reads.
    #[must_use]
    pub fn with_provider(mut self, provider: ProviderRef) -> Self {
        self.provider = Some(provider);
        self
    }

    /// Compute the stable input reference used for deduplication.
    pub fn input_ref(&self) -> InputRef {
        input_ref(&self.input, &self.context)
    }

    /// Validate payload/context coherence and return a representation-aware
    /// identity suitable for subscriber and runtime deduplication.
    ///
    /// Validation is fail-closed for canonical logs: their block, transaction,
    /// and log positions must be complete and agree with the context. Block and
    /// pending-transaction representations receive the corresponding lifecycle,
    /// inclusion-wrapper, and payload/context checks. This does not recompute a
    /// claimed header hash, transaction root, or transaction signature; exact
    /// subscriber payload commitments remain the transport-integrity boundary
    /// for those cryptographic claims.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveError::InvalidInputRecord`] when the payload,
    /// lifecycle, inclusion metadata, or context is incomplete or internally
    /// inconsistent.
    pub fn validated_identity(&self) -> Result<ReactiveInputIdentity, ReactiveError> {
        validate_input_record(self)?;
        let kind = match &self.input {
            ReactiveInput::Log(log)
                if log.removed
                    || matches!(self.context.chain_status, ChainStatus::Reorged { .. }) =>
            {
                ReactiveInputKind::ReorgSignalLog
            }
            ReactiveInput::Log(_) => ReactiveInputKind::CanonicalLog,
            ReactiveInput::BlockHeader(_) => ReactiveInputKind::BlockHeader,
            ReactiveInput::FullBlock(_) => ReactiveInputKind::FullBlock,
            ReactiveInput::PendingTxHash(_) => ReactiveInputKind::PendingTxHash,
            ReactiveInput::PendingTx(_) => ReactiveInputKind::PendingTx,
        };
        ReactiveInputIdentity::try_from_parts(self.input_ref(), kind).map_err(|error| {
            ReactiveError::InvalidInputRecord {
                message: error.to_string(),
            }
        })
    }

    /// Whether two same-identity records carry the same deduplicable payload.
    ///
    /// This deliberately ignores [`ReactiveContext`]: the same provider object
    /// can legitimately arrive from backfill and subscription transports with
    /// different provenance or confirmation metadata. Callers must first
    /// compare [`validated_identity`](Self::validated_identity) and reconcile
    /// lifecycle/context authority separately. Logs are compared structurally;
    /// block and transaction hashes are cryptographic commitments for the
    /// remaining same-representation payloads. Full block responses and
    /// hydrated pending transaction bodies deliberately return `false`: the
    /// core does not currently prove a supplied body against the header's
    /// transaction root or compare every response field, so a composite source
    /// must preserve both rather than suppress one based only on its hash.
    pub fn same_deduplicable_payload(&self, other: &Self) -> bool {
        match (&self.input, &other.input) {
            (ReactiveInput::Log(left), ReactiveInput::Log(right)) => {
                left.inner == right.inner
                    && left.block_hash == right.block_hash
                    && left.block_number == right.block_number
                    && optional_metadata_compatible(
                        left.block_timestamp.as_ref(),
                        right.block_timestamp.as_ref(),
                    )
                    && left.transaction_hash == right.transaction_hash
                    && left.transaction_index == right.transaction_index
                    && left.log_index == right.log_index
                    && left.removed == right.removed
            }
            (ReactiveInput::BlockHeader(left), ReactiveInput::BlockHeader(right)) => {
                left.hash() == right.hash()
            }
            (ReactiveInput::FullBlock(_), ReactiveInput::FullBlock(_)) => false,
            (ReactiveInput::PendingTxHash(left), ReactiveInput::PendingTxHash(right)) => {
                left == right
            }
            (ReactiveInput::PendingTx(_), ReactiveInput::PendingTx(_)) => false,
            _ => false,
        }
    }

    /// Whether this representation has a complete payload-equivalence contract
    /// and may participate in duplicate suppression.
    ///
    /// Full block and hydrated pending transaction bodies are intentionally
    /// excluded until their complete body/response integrity is validated.
    pub fn is_payload_deduplicable(&self) -> bool {
        matches!(
            &self.input,
            ReactiveInput::Log(_) | ReactiveInput::BlockHeader(_) | ReactiveInput::PendingTxHash(_)
        )
    }

    /// Merge `other` when it is the same safely deduplicable provider object.
    ///
    /// Returns `Ok(false)` for a different identity or a representation whose
    /// complete payload cannot be proven equivalent. A same-identity payload or
    /// semantic conflict returns an error. Successful merges are deterministic:
    /// optional block/timestamp metadata is enriched, canonical lifecycle moves
    /// toward `Finalized` then `Safe` then the highest-confirmation `Included`,
    /// and provenance uses a stable source priority. The result is therefore
    /// independent of historical/live arrival order.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveError`] when either record is invalid, or when equal
    /// identities carry conflicting payload or semantic context.
    pub fn merge_compatible_duplicate(&mut self, other: &Self) -> Result<bool, ReactiveError> {
        let identity = self.validated_identity()?;
        let other_identity = other.validated_identity()?;
        if identity != other_identity
            || !self.is_payload_deduplicable()
            || !other.is_payload_deduplicable()
        {
            return Ok(false);
        }
        if !self.same_deduplicable_payload(other) || !self.dedupe_context_is_compatible(other) {
            return Err(ReactiveError::InvalidInputRecord {
                message: format!(
                    "conflicting payload or semantic context for identity {:?}",
                    identity
                ),
            });
        }
        let mut merged = self.clone();
        merge_deduplicable_record(&mut merged, other);
        merged.validated_identity()?;
        *self = merged;
        Ok(true)
    }

    /// Whether semantic context agrees for deduplication across transports.
    ///
    /// Provenance source and confirmation count may legitimately differ at a
    /// historical/live overlap and are ignored. Chain id, lifecycle class, and
    /// transaction/log positions must agree. Block number/hash are exact;
    /// optional parent/timestamp metadata may be enriched by one source but two
    /// present conflicting values are rejected.
    pub fn dedupe_context_is_compatible(&self, other: &Self) -> bool {
        let left = &self.context;
        let right = &other.context;
        left.chain_id == right.chain_id
            && optional_block_refs_are_compatible(left.block.as_ref(), right.block.as_ref())
            && left.transaction_index == right.transaction_index
            && left.log_index == right.log_index
            && chain_statuses_are_dedupe_compatible(&left.chain_status, &right.chain_status)
    }
}

fn chain_statuses_are_dedupe_compatible(left: &ChainStatus, right: &ChainStatus) -> bool {
    match (left, right) {
        (ChainStatus::Pending, ChainStatus::Pending)
        | (ChainStatus::Reorged { .. }, ChainStatus::Reorged { .. }) => true,
        (
            ChainStatus::Preconfirmed { flashblock: left },
            ChainStatus::Preconfirmed { flashblock: right },
        ) => left == right,
        (
            ChainStatus::Included { .. } | ChainStatus::Safe { .. } | ChainStatus::Finalized { .. },
            ChainStatus::Included { .. } | ChainStatus::Safe { .. } | ChainStatus::Finalized { .. },
        ) => true,
        _ => false,
    }
}

fn optional_metadata_compatible<T: PartialEq>(left: Option<&T>, right: Option<&T>) -> bool {
    left.zip(right).is_none_or(|(left, right)| left == right)
}

fn optional_block_refs_are_compatible(left: Option<&BlockRef>, right: Option<&BlockRef>) -> bool {
    match (left, right) {
        (None, None) => true,
        (Some(left), Some(right)) => {
            left.number == right.number
                && left.hash == right.hash
                && optional_metadata_compatible(
                    left.parent_hash.as_ref(),
                    right.parent_hash.as_ref(),
                )
                && optional_metadata_compatible(left.timestamp.as_ref(), right.timestamp.as_ref())
        }
        _ => false,
    }
}

fn merge_deduplicable_record<N: Network>(
    retained: &mut ReactiveInputRecord<N>,
    incoming: &ReactiveInputRecord<N>,
) {
    if let (ReactiveInput::Log(retained), ReactiveInput::Log(incoming)) =
        (&mut retained.input, &incoming.input)
        && retained.block_timestamp.is_none()
    {
        retained.block_timestamp = incoming.block_timestamp;
    }
    if let (Some(retained), Some(incoming)) =
        (&mut retained.context.block, incoming.context.block.as_ref())
    {
        enrich_block_ref(retained, incoming);
    }
    retained.context.chain_status = merged_chain_status(
        &retained.context.chain_status,
        &incoming.context.chain_status,
    );
    if input_source_rank(incoming.context.source) > input_source_rank(retained.context.source) {
        retained.context.source = incoming.context.source;
    }
    if retained.provider.is_none() {
        retained.provider = incoming.provider.clone();
    }
}

fn enrich_block_ref(retained: &mut BlockRef, incoming: &BlockRef) {
    if retained.parent_hash.is_none() {
        retained.parent_hash = incoming.parent_hash;
    }
    if retained.timestamp.is_none() {
        retained.timestamp = incoming.timestamp;
    }
}

fn merged_chain_status(retained: &ChainStatus, incoming: &ChainStatus) -> ChainStatus {
    let merged_block = |left: &BlockRef, right: &BlockRef| {
        let mut block = *left;
        enrich_block_ref(&mut block, right);
        block
    };
    match (retained, incoming) {
        (ChainStatus::Pending, ChainStatus::Pending) => ChainStatus::Pending,
        (
            ChainStatus::Preconfirmed { flashblock: left },
            ChainStatus::Preconfirmed { flashblock: right },
        ) => {
            debug_assert_eq!(left, right, "compatible pre-confirmed records agree");
            ChainStatus::Preconfirmed {
                flashblock: left.clone(),
            }
        }
        (
            ChainStatus::Reorged { dropped_from: left },
            ChainStatus::Reorged {
                dropped_from: right,
            },
        ) => ChainStatus::Reorged {
            dropped_from: merged_block(left, right),
        },
        (left, right) => {
            let (left_block, left_rank, left_confirmations) = canonical_status_parts(left)
                .expect("compatible duplicate has a canonical lifecycle");
            let (right_block, right_rank, right_confirmations) = canonical_status_parts(right)
                .expect("compatible duplicate has a canonical lifecycle");
            let block = merged_block(left_block, right_block);
            let rank = left_rank.max(right_rank);
            match rank {
                3 => ChainStatus::Finalized { block },
                2 => ChainStatus::Safe { block },
                _ => ChainStatus::Included {
                    block,
                    confirmations: left_confirmations.max(right_confirmations),
                },
            }
        }
    }
}

fn canonical_status_parts(status: &ChainStatus) -> Option<(&BlockRef, u8, u64)> {
    match status {
        ChainStatus::Included {
            block,
            confirmations,
        } => Some((block, 1, *confirmations)),
        ChainStatus::Safe { block } => Some((block, 2, 0)),
        ChainStatus::Finalized { block } => Some((block, 3, 0)),
        ChainStatus::Pending | ChainStatus::Preconfirmed { .. } | ChainStatus::Reorged { .. } => {
            None
        }
    }
}

fn input_source_rank(source: InputSource) -> u8 {
    match source {
        InputSource::Backfill => 0,
        InputSource::Poll => 1,
        InputSource::Subscription => 2,
        InputSource::Flashblocks => 3,
        InputSource::Batch => 4,
        InputSource::Synthetic => 5,
    }
}

/// Opaque subscriber-owned token attached to a delivered input batch.
///
/// Subscribers that provide durable, at-least-once delivery can use this token
/// to identify the batch that becomes committable after runtime ingestion
/// succeeds. The runtime never interprets the bytes. A token must be immutable,
/// stable across replay, and must never identify two different batch payloads.
/// Subscriber implementations must preserve delivery order while one token is
/// awaiting acknowledgement; [`ReactiveEngine`] retries it before polling a
/// later batch.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct SubscriberDeliveryToken(Vec<u8>);

impl SubscriberDeliveryToken {
    /// Create an opaque delivery token from subscriber-owned bytes.
    pub fn new(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }

    /// Borrow the opaque token bytes.
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Consume the token into its opaque bytes.
    pub fn into_bytes(self) -> Vec<u8> {
        self.0
    }
}

/// Opaque source checkpoint associated with a delivered batch.
///
/// Unlike [`SubscriberDeliveryToken`], which identifies the delivery to
/// acknowledge, this value describes provider-specific resume state. The core
/// crate persists and returns the bytes without interpreting their format.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct SubscriberCheckpoint(Vec<u8>);

impl SubscriberCheckpoint {
    /// Create an opaque source checkpoint from subscriber-owned bytes.
    pub fn new(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }

    /// Borrow the opaque checkpoint bytes.
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Consume the checkpoint into its opaque bytes.
    pub fn into_bytes(self) -> Vec<u8> {
        self.0
    }
}

/// Subscriber-supplied commitment to the exact canonical wire payload of one
/// delivered batch.
///
/// The core includes this value in its durable replay witness. It is required
/// for tokened block-header, full-block, and hydrated-transaction payloads whose
/// network-generic Rust response types cannot be serialized completely by the
/// core. The source must recompute the commitment from a stable canonical
/// encoding on every replay; reusing a commitment for changed bytes violates the
/// [`EventSubscriber`] contract.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct SubscriberPayloadCommitment(B256);

impl SubscriberPayloadCommitment {
    /// Wrap a cryptographic commitment produced by the subscriber.
    pub const fn new(commitment: B256) -> Self {
        Self(commitment)
    }

    /// Return the committed digest.
    pub const fn digest(&self) -> B256 {
        self.0
    }
}

/// Durable subscriber position restored together with cache/runtime state.
///
/// The core never interprets provider checkpoint bytes. Composite and remote
/// subscribers use this synchronous hand-off to seed their source cursors,
/// replay fences, and canonical overlap journals before polling resumes.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub struct SubscriberResumePosition {
    /// Chain whose canonical position and provider cursor are being restored.
    pub chain_id: u64,
    /// Authoritative canonical coverage embodied by the restored cache.
    pub coverage_head: BlockRef,
    /// Ordered canonical identities still retained for in-window reconciliation.
    pub canonical_history: Vec<BlockRef>,
    /// Last delivery token whose effects are already represented by the cache.
    /// It may still be pending at the source when the process stopped after its
    /// durable save but before the source acknowledgement committed.
    pub delivery_token: Option<SubscriberDeliveryToken>,
    /// Provider-specific durable cursor committed with that delivery.
    pub subscriber_checkpoint: Option<SubscriberCheckpoint>,
}

impl SubscriberResumePosition {
    /// Construct a complete restored subscriber position.
    pub fn new(
        chain_id: u64,
        coverage_head: BlockRef,
        canonical_history: Vec<BlockRef>,
        delivery_token: Option<SubscriberDeliveryToken>,
        subscriber_checkpoint: Option<SubscriberCheckpoint>,
    ) -> Self {
        Self {
            chain_id,
            coverage_head,
            canonical_history,
            delivery_token,
            subscriber_checkpoint,
        }
    }
}

/// Runtime routing audience for one delivered subscriber batch.
///
/// Historical catch-up for a newly registered handler must not be routed
/// through older handlers whose filters happen to overlap. Subscribers retain
/// that provenance by targeting the batch at the exact logical owners that
/// requested it. Ordinary canonical delivery remains broadcast to every
/// matching handler.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum DeliveryAudience {
    /// Route each record through every matching registered handler.
    #[default]
    All,
    /// Route each record only through the named matching handlers.
    Owners(Vec<HandlerId>),
    /// Route through every matching handler except the named owners.
    ///
    /// Composite subscribers use this to deliver the residual audience after an
    /// overlapping source already committed the same input for selected owners.
    AllExcept(Vec<HandlerId>),
}

/// How one delivered record participates in the runtime's canonical state machine.
///
/// Routing and chain authority are deliberately independent: [`DeliveryAudience`]
/// selects handlers, while this value decides whether a record may advance or
/// rewind global chain state. Historical replay for a newly added owner must use
/// [`OwnerCatchup`](Self::OwnerCatchup), even though its original on-chain status
/// is canonical.
#[derive(
    Clone, Copy, Debug, Default, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize,
)]
#[non_exhaustive]
pub enum DeliveryScope {
    /// Authoritative live canonical delivery.
    #[default]
    Canonical,
    /// Authoritative historical/recovery delivery that advances canonical progress.
    CanonicalProgress,
    /// Historical replay routed to selected owners without changing global chain state.
    OwnerCatchup,
    /// Ephemeral pre-confirmation delivery applied only to the speculative
    /// cache overlay.
    Preconfirmed,
}

impl DeliveryScope {
    const fn advances_canonical_state(self) -> bool {
        matches!(self, Self::Canonical | Self::CanonicalProgress)
    }
}

/// One input together with its routing and canonical-processing provenance.
#[derive(Clone, Debug)]
pub struct ReactiveInputDelivery<N: Network = Ethereum> {
    record: ReactiveInputRecord<N>,
    audience: DeliveryAudience,
    scope: DeliveryScope,
}

impl<N: Network> ReactiveInputDelivery<N> {
    /// Construct one lossless delivered record.
    pub fn new(
        record: ReactiveInputRecord<N>,
        audience: DeliveryAudience,
        scope: DeliveryScope,
    ) -> Self {
        Self {
            record,
            audience,
            scope,
        }
    }

    /// Borrow the runtime input record.
    pub const fn record(&self) -> &ReactiveInputRecord<N> {
        &self.record
    }

    /// Borrow the exact routing audience.
    pub const fn audience(&self) -> &DeliveryAudience {
        &self.audience
    }

    /// Return the record's canonical-processing scope.
    pub const fn scope(&self) -> DeliveryScope {
        self.scope
    }

    /// Consume this value into its complete parts.
    pub fn into_parts(self) -> (ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope) {
        (self.record, self.audience, self.scope)
    }
}

/// Complete contents of a consumed [`ReactiveInputBatch`].
///
/// Use this instead of [`ReactiveInputBatch::into_records`], which intentionally
/// discards subscriber commit and chain-lifecycle metadata.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct ReactiveInputBatchParts<N: Network = Ethereum> {
    /// Authoritative chain identity for controls and records in this batch.
    pub chain_id: Option<u64>,
    /// Records with per-record routing and chain provenance.
    pub deliveries: Vec<ReactiveInputDelivery<N>>,
    /// Subscriber delivery token committed after ingestion.
    pub delivery_token: Option<SubscriberDeliveryToken>,
    /// Provider-specific resume cursor associated with the delivery.
    pub subscriber_checkpoint: Option<SubscriberCheckpoint>,
    /// Exact opaque wire-payload commitment supplied by the subscriber.
    pub payload_commitment: Option<SubscriberPayloadCommitment>,
    /// Ordered chain controls sharing the delivery's commit boundary.
    pub chain_controls: Vec<ChainControl>,
}

/// Batch of reactive input records.
#[derive(Clone, Debug)]
pub struct ReactiveInputBatch<N: Network = Ethereum> {
    records: Vec<ReactiveInputRecord<N>>,
    chain_id: Option<u64>,
    delivery_token: Option<SubscriberDeliveryToken>,
    subscriber_checkpoint: Option<SubscriberCheckpoint>,
    payload_commitment: Option<SubscriberPayloadCommitment>,
    audience: DeliveryAudience,
    record_audiences: Option<Vec<DeliveryAudience>>,
    delivery_scope: DeliveryScope,
    record_delivery_scopes: Option<Vec<DeliveryScope>>,
    chain_controls: Vec<ChainControl>,
}

type RuntimeInputDelivery<N> = (ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope);

impl<N: Network> ReactiveInputBatch<N> {
    /// Create a batch from records.
    pub fn new(records: Vec<ReactiveInputRecord<N>>) -> Self {
        let chain_id = common_record_chain_id(&records);
        Self {
            records,
            chain_id,
            delivery_token: None,
            subscriber_checkpoint: None,
            payload_commitment: None,
            audience: DeliveryAudience::All,
            record_audiences: None,
            delivery_scope: DeliveryScope::Canonical,
            record_delivery_scopes: None,
            chain_controls: Vec::new(),
        }
    }

    /// Bind the complete batch, including control-only progress/finality, to a
    /// chain. Runtime ingestion rejects a different cache chain.
    pub fn with_chain_id(mut self, chain_id: u64) -> Self {
        self.chain_id = Some(chain_id);
        self
    }

    /// Authoritative batch chain identity, when supplied or unambiguously
    /// derived from its records.
    pub const fn chain_id(&self) -> Option<u64> {
        self.chain_id
    }

    /// Attach the subscriber-owned token committed after successful ingestion.
    pub fn with_delivery_token(mut self, token: SubscriberDeliveryToken) -> Self {
        self.delivery_token = Some(token);
        self
    }

    /// Borrow the subscriber-owned delivery token, when present.
    pub fn delivery_token(&self) -> Option<&SubscriberDeliveryToken> {
        self.delivery_token.as_ref()
    }

    /// Attach provider-specific resume state included by this delivery.
    pub fn with_subscriber_checkpoint(mut self, checkpoint: SubscriberCheckpoint) -> Self {
        self.subscriber_checkpoint = Some(checkpoint);
        self
    }

    /// Borrow provider-specific resume state, when present.
    pub fn subscriber_checkpoint(&self) -> Option<&SubscriberCheckpoint> {
        self.subscriber_checkpoint.as_ref()
    }

    /// Attach a commitment to the exact canonical wire payload represented by
    /// this batch.
    pub fn with_payload_commitment(mut self, commitment: SubscriberPayloadCommitment) -> Self {
        self.payload_commitment = Some(commitment);
        self
    }

    /// Borrow the subscriber-supplied exact payload commitment, when present.
    pub const fn payload_commitment(&self) -> Option<&SubscriberPayloadCommitment> {
        self.payload_commitment.as_ref()
    }

    /// Restrict runtime routing to exact logical interest owners.
    pub fn with_audience(mut self, audience: DeliveryAudience) -> Self {
        self.audience = audience;
        self.record_audiences = None;
        self
    }

    /// Delivery audience captured by the subscriber.
    pub const fn audience(&self) -> &DeliveryAudience {
        &self.audience
    }

    /// Create a batch whose records retain independent delivery audiences.
    pub fn from_scoped_records(
        records: impl IntoIterator<Item = (ReactiveInputRecord<N>, DeliveryAudience)>,
    ) -> Self {
        let (records, record_audiences): (Vec<_>, Vec<_>) = records.into_iter().unzip();
        let chain_id = common_record_chain_id(&records);
        Self {
            records,
            chain_id,
            delivery_token: None,
            subscriber_checkpoint: None,
            payload_commitment: None,
            audience: DeliveryAudience::All,
            record_audiences: Some(record_audiences),
            delivery_scope: DeliveryScope::Canonical,
            record_delivery_scopes: None,
            chain_controls: Vec::new(),
        }
    }

    /// Create a batch with independent routing and canonical provenance per record.
    pub fn from_deliveries(deliveries: impl IntoIterator<Item = ReactiveInputDelivery<N>>) -> Self {
        Self::from_scoped_records_with_delivery_scope(
            deliveries
                .into_iter()
                .map(ReactiveInputDelivery::into_parts),
        )
    }

    /// Audience for the record at `index`.
    pub fn record_audience(&self, index: usize) -> Option<&DeliveryAudience> {
        if index >= self.records.len() {
            return None;
        }
        Some(
            self.record_audiences
                .as_ref()
                .and_then(|audiences| audiences.get(index))
                .unwrap_or(&self.audience),
        )
    }

    /// Set how every record in this batch participates in canonical state.
    pub fn with_delivery_scope(mut self, scope: DeliveryScope) -> Self {
        self.delivery_scope = scope;
        self.record_delivery_scopes = None;
        self
    }

    /// Canonical-processing scope for the record at `index`.
    pub fn record_delivery_scope(&self, index: usize) -> Option<DeliveryScope> {
        if index >= self.records.len() {
            return None;
        }
        Some(
            self.record_delivery_scopes
                .as_ref()
                .and_then(|scopes| scopes.get(index))
                .copied()
                .unwrap_or(self.delivery_scope),
        )
    }

    fn from_scoped_records_with_delivery_scope(
        records: impl IntoIterator<Item = (ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)>,
    ) -> Self {
        let mut input_records = Vec::new();
        let mut audiences = Vec::new();
        let mut scopes = Vec::new();
        for (record, audience, scope) in records {
            input_records.push(record);
            audiences.push(audience);
            scopes.push(scope);
        }
        let chain_id = common_record_chain_id(&input_records);
        Self {
            records: input_records,
            chain_id,
            delivery_token: None,
            subscriber_checkpoint: None,
            payload_commitment: None,
            audience: DeliveryAudience::All,
            record_audiences: Some(audiences),
            delivery_scope: DeliveryScope::Canonical,
            record_delivery_scopes: Some(scopes),
            chain_controls: Vec::new(),
        }
    }

    /// Attach ordered chain-lifecycle controls to this delivery.
    ///
    /// A control-only batch must also call [`with_chain_id`](Self::with_chain_id).
    /// When records are present, their unanimous chain id is derived by the
    /// constructor; a missing or cache-mismatched authoritative batch identity
    /// is rejected before any control mutates runtime state.
    pub fn with_chain_controls(mut self, controls: impl IntoIterator<Item = ChainControl>) -> Self {
        self.chain_controls = controls.into_iter().collect();
        self
    }

    /// Ordered chain-lifecycle controls in this delivery.
    pub fn chain_controls(&self) -> &[ChainControl] {
        &self.chain_controls
    }

    /// Borrow the records in this batch.
    pub fn records(&self) -> &[ReactiveInputRecord<N>] {
        &self.records
    }

    /// Consume the batch into only its input records.
    ///
    /// This is intentionally lossy: it discards the authoritative batch chain
    /// identity, routing audiences, delivery scopes, ordered chain controls,
    /// acknowledgement tokens, and provider checkpoints. Adapters should use
    /// [`into_parts`](Self::into_parts) instead.
    pub fn into_records(self) -> Vec<ReactiveInputRecord<N>> {
        self.records
    }

    /// Consume the batch without losing subscriber or chain-lifecycle metadata.
    pub fn into_parts(self) -> ReactiveInputBatchParts<N> {
        let chain_id = self.chain_id;
        let delivery_token = self.delivery_token;
        let subscriber_checkpoint = self.subscriber_checkpoint;
        let payload_commitment = self.payload_commitment;
        let chain_controls = self.chain_controls;
        let audiences = self
            .record_audiences
            .unwrap_or_else(|| vec![self.audience; self.records.len()]);
        let scopes = self
            .record_delivery_scopes
            .unwrap_or_else(|| vec![self.delivery_scope; self.records.len()]);
        let deliveries = self
            .records
            .into_iter()
            .zip(audiences)
            .zip(scopes)
            .map(|((record, audience), scope)| ReactiveInputDelivery::new(record, audience, scope))
            .collect();
        ReactiveInputBatchParts {
            chain_id,
            deliveries,
            delivery_token,
            subscriber_checkpoint,
            payload_commitment,
            chain_controls,
        }
    }

    fn into_runtime_parts(self) -> (Vec<RuntimeInputDelivery<N>>, Vec<ChainControl>, Option<u64>) {
        let audiences = self
            .record_audiences
            .unwrap_or_else(|| vec![self.audience; self.records.len()]);
        let scopes = self
            .record_delivery_scopes
            .unwrap_or_else(|| vec![self.delivery_scope; self.records.len()]);
        let records = self
            .records
            .into_iter()
            .zip(audiences)
            .zip(scopes)
            .map(|((record, audience), scope)| (record, audience, scope))
            .collect();
        (records, self.chain_controls, self.chain_id)
    }

    fn take_delivery_token(&mut self) -> Option<SubscriberDeliveryToken> {
        self.delivery_token.take()
    }

    fn take_subscriber_checkpoint(&mut self) -> Option<SubscriberCheckpoint> {
        self.subscriber_checkpoint.take()
    }
}

fn common_record_chain_id<N: Network>(records: &[ReactiveInputRecord<N>]) -> Option<u64> {
    let chain_id = records.first()?.context.chain_id?;
    records
        .iter()
        .all(|record| record.context.chain_id == Some(chain_id))
        .then_some(chain_id)
}

/// Pure synchronous handler for reactive inputs.
pub trait ReactiveHandler<N: Network = Ethereum>: Send + Sync {
    /// Stable handler id.
    fn id(&self) -> HandlerId;

    /// Interests used by subscribers and the local router.
    fn interests(&self) -> Vec<ReactiveInterest<N>>;

    /// Exhaustive exact keys for log inputs this handler can accept.
    ///
    /// Returning `None` keeps the handler on the compatibility fallback path.
    /// Returning an index promises that every matching log has at least one of
    /// its keys; the registry still re-checks the handler's original
    /// [`LogInterest`]s and local matchers before dispatch.
    fn log_route_index(&self) -> Option<LogRouteIndex> {
        None
    }

    /// Handle one input against a read-only cache view.
    fn handle(
        &self,
        ctx: &ReactiveContext,
        input: &ReactiveInput<N>,
        state: &dyn StateView,
    ) -> Result<HandlerOutcome, HandlerError>;
}

/// Hook invoked after reports are built and cache mutation phases have ended.
///
/// Hooks are synchronous in-process observers, not a durable transactional
/// outbox. The runtime never dispatches reports for a batch it rejects or rolls
/// back during checkpoint staging, and it dispatches a successfully staged
/// batch at most once per live engine. A process crash can still occur between
/// hook dispatch and durable checkpoint or transport acknowledgement. External
/// side effects therefore need their own idempotency key (normally an
/// [`InputRef`] or [`SubscriberDeliveryToken`]) and durable delivery mechanism.
pub trait ReactiveHook<N: Network = Ethereum>: Send + Sync {
    /// Observe a runtime report.
    fn on_report(&self, report: Arc<ReactiveReport<N>>);
}

/// Reactive subscription interest.
#[allow(clippy::large_enum_variant)]
#[derive(Clone)]
pub enum ReactiveInterest<N: Network = Ethereum> {
    /// Log interest.
    Logs(LogInterest),
    /// Block interest.
    Blocks(BlockInterest),
    /// Pending transaction interest.
    PendingTransactions(PendingTxInterest<N>),
}

impl<N: Network> fmt::Debug for ReactiveInterest<N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Logs(interest) => f.debug_tuple("Logs").field(interest).finish(),
            Self::Blocks(interest) => f.debug_tuple("Blocks").field(interest).finish(),
            Self::PendingTransactions(interest) => f
                .debug_tuple("PendingTransactions")
                .field(interest)
                .finish(),
        }
    }
}

/// Interest in logs.
#[derive(Clone)]
pub struct LogInterest {
    /// Provider-side filter.
    pub provider_filter: Filter,
    /// Optional local matcher for predicates providers cannot express.
    pub local_matcher: Option<Arc<dyn LogMatcher>>,
    /// Optional route-key extraction strategy.
    pub route_key: Option<RouteKeySpec>,
}

impl LogInterest {
    /// Return true if the log matches both the provider filter and local matcher.
    pub fn matches(&self, log: &Log) -> bool {
        self.provider_filter.rpc_matches(log)
            && self
                .local_matcher
                .as_ref()
                .is_none_or(|matcher| matcher.matches(log))
    }

    /// Extract the route key for a matching log, if configured.
    pub fn route_key(&self, log: &Log) -> Option<RouteKey> {
        self.route_key.as_ref().and_then(|spec| spec.extract(log))
    }
}

impl fmt::Debug for LogInterest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("LogInterest")
            .field("provider_filter", &self.provider_filter)
            .field(
                "local_matcher",
                &self.local_matcher.as_ref().map(|_| "<matcher>"),
            )
            .field("route_key", &self.route_key)
            .finish()
    }
}

/// Local log predicate.
pub trait LogMatcher: Send + Sync {
    /// Return true when the log should be routed to the handler.
    fn matches(&self, log: &Log) -> bool;
}

/// Route-key extraction strategy for logs.
#[derive(Clone)]
pub enum RouteKeySpec {
    /// Route by emitting address.
    EmitterAddress,
    /// Route by indexed topic.
    Topic {
        /// Topic index.
        index: usize,
    },
    /// Route by a byte slice in log data.
    DataSlice {
        /// Byte offset in the data payload.
        offset: usize,
        /// Number of bytes to copy.
        len: usize,
    },
    /// Custom extractor.
    Custom(Arc<dyn RouteKeyExtractor>),
}

impl RouteKeySpec {
    /// Extract a route key from a log.
    pub fn extract(&self, log: &Log) -> Option<RouteKey> {
        match self {
            Self::EmitterAddress => Some(RouteKey::Address(log.address())),
            Self::Topic { index } => log.topics().get(*index).copied().map(RouteKey::Bytes32),
            Self::DataSlice { offset, len } => {
                let data = log.inner.data.data.as_ref();
                let end = offset.checked_add(*len)?;
                data.get(*offset..end)
                    .map(|bytes| RouteKey::Bytes(bytes.to_vec()))
            }
            Self::Custom(extractor) => extractor.extract(log),
        }
    }
}

impl fmt::Debug for RouteKeySpec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmitterAddress => f.write_str("EmitterAddress"),
            Self::Topic { index } => f.debug_struct("Topic").field("index", index).finish(),
            Self::DataSlice { offset, len } => f
                .debug_struct("DataSlice")
                .field("offset", offset)
                .field("len", len)
                .finish(),
            Self::Custom(_) => f.write_str("Custom(<extractor>)"),
        }
    }
}

/// Extracts custom route keys from logs.
pub trait RouteKeyExtractor: Send + Sync {
    /// Extract a route key.
    fn extract(&self, log: &Log) -> Option<RouteKey>;
}

/// Extracted route key.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum RouteKey {
    /// Address key.
    Address(Address),
    /// 32-byte key.
    Bytes32(B256),
    /// Arbitrary bytes key.
    Bytes(Vec<u8>),
}

/// Exact protocol-neutral key used to select candidate log handlers.
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum LogRouteKey {
    /// Emitting contract address.
    Emitter(Address),
    /// Exact indexed topic.
    Topic {
        /// Topic position in the log.
        index: usize,
        /// Expected topic value.
        value: B256,
    },
    /// Exact byte slice in the log data.
    DataSlice {
        /// Byte offset in the data payload.
        offset: usize,
        /// Expected bytes.
        value: Vec<u8>,
    },
}

/// Non-empty exhaustive OR-set of exact log route keys.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct LogRouteIndex {
    keys: Vec<LogRouteKey>,
}

impl LogRouteIndex {
    /// Construct an index from one required key and optional additional keys.
    pub fn new(primary: LogRouteKey, additional: impl IntoIterator<Item = LogRouteKey>) -> Self {
        let mut keys = vec![primary];
        for key in additional {
            if !keys.contains(&key) {
                keys.push(key);
            }
        }
        Self { keys }
    }

    /// Construct a single-key index.
    pub fn single(key: LogRouteKey) -> Self {
        Self { keys: vec![key] }
    }

    /// Exact keys in declaration order.
    pub fn keys(&self) -> &[LogRouteKey] {
        &self.keys
    }
}

/// Exact log route selected by [`ReactiveRegistry::route_log`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReactiveLogRoute {
    /// Handler whose log interest matched.
    pub handler_id: HandlerId,
    /// Optional route key extracted from the matching log interest.
    pub route_key: Option<RouteKey>,
}

/// Interest in block inputs.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct BlockInterest {
    /// Block input mode.
    pub mode: BlockInterestMode,
}

impl Default for BlockInterest {
    fn default() -> Self {
        Self {
            mode: BlockInterestMode::Header,
        }
    }
}

/// Block subscription mode.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum BlockInterestMode {
    /// Header-only block input.
    Header,
    /// Full block input.
    FullBlock,
}

/// Interest in pending transaction inputs.
#[derive(Clone)]
pub struct PendingTxInterest<N: Network = Ethereum> {
    /// Whether the handler requires full transaction bodies.
    pub full_transactions: bool,
    /// Sender matcher.
    pub from: AddressMatcher,
    /// Recipient matcher.
    pub to: AddressMatcher,
    /// Calldata selector matcher.
    pub selectors: SelectorMatcher,
    /// Optional local transaction matcher.
    pub local_matcher: Option<Arc<dyn PendingTxMatcher<N>>>,
}

impl<N: Network> Default for PendingTxInterest<N> {
    fn default() -> Self {
        Self {
            full_transactions: false,
            from: AddressMatcher::Any,
            to: AddressMatcher::Any,
            selectors: SelectorMatcher::Any,
            local_matcher: None,
        }
    }
}

impl<N: Network> PendingTxInterest<N> {
    fn matches_hash_only(&self) -> bool {
        !self.full_transactions
            && self.from.is_any()
            && self.to.is_any()
            && self.selectors.is_any()
            && self.local_matcher.is_none()
    }

    fn matches_tx(&self, tx: &N::TransactionResponse) -> bool {
        self.from.matches(tx.from())
            && self.to.matches_option(tx.to())
            && self.selectors.matches(tx.input())
            && self
                .local_matcher
                .as_ref()
                .is_none_or(|matcher| matcher.matches(tx))
    }
}

impl<N: Network> fmt::Debug for PendingTxInterest<N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("PendingTxInterest")
            .field("full_transactions", &self.full_transactions)
            .field("from", &self.from)
            .field("to", &self.to)
            .field("selectors", &self.selectors)
            .field(
                "local_matcher",
                &self.local_matcher.as_ref().map(|_| "<matcher>"),
            )
            .finish()
    }
}

/// Address matching helper for pending transaction interests.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum AddressMatcher {
    /// Match every address.
    Any,
    /// Match one address.
    Exact(Address),
    /// Match any address in the list.
    AnyOf(Vec<Address>),
}

impl AddressMatcher {
    /// Return true when the matcher is unconstrained.
    pub fn is_any(&self) -> bool {
        matches!(self, Self::Any)
    }

    /// Match a present address.
    pub fn matches(&self, address: Address) -> bool {
        match self {
            Self::Any => true,
            Self::Exact(expected) => *expected == address,
            Self::AnyOf(addresses) => addresses.contains(&address),
        }
    }

    /// Match an optional address.
    pub fn matches_option(&self, address: Option<Address>) -> bool {
        match (self, address) {
            (Self::Any, _) => true,
            (_, Some(address)) => self.matches(address),
            _ => false,
        }
    }
}

/// Calldata selector matching helper.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum SelectorMatcher {
    /// Match every selector.
    Any,
    /// Match any selector in the list.
    AnyOf(Vec<[u8; 4]>),
}

impl SelectorMatcher {
    /// Return true when the matcher is unconstrained.
    pub fn is_any(&self) -> bool {
        matches!(self, Self::Any)
    }

    /// Match calldata bytes.
    pub fn matches(&self, input: &Bytes) -> bool {
        match self {
            Self::Any => true,
            Self::AnyOf(selectors) => input
                .get(..4)
                .and_then(|bytes| bytes.try_into().ok())
                .is_some_and(|selector| selectors.contains(&selector)),
        }
    }
}

/// Local predicate over a full pending transaction.
pub trait PendingTxMatcher<N: Network = Ethereum>: Send + Sync {
    /// Return true when the transaction should be routed to the handler.
    fn matches(&self, tx: &N::TransactionResponse) -> bool;
}

/// How a tracked account is kept live by the per-block root gate (Phase-8 step 4).
///
/// The `storageHash` root gate behaves *oppositely* for two contract shapes, so
/// liveness strategy is per-contract:
///
/// - A sparse-interest contract (a few balance slots, e.g. WETH) has its root
///   churn on nearly every block, so the root is a noisy gate — [`Slots`] opts
///   out. Its enumerated slots stay fresh via decoders + cadence reconcile.
/// - A whole-economic-state contract (e.g. a Uniswap-V2 pool) has
///   `root_moved ≈ my_state_changed`, so [`WholeAccount`] opts in: probe the root
///   each canonical block; a move a decoder did not cover is a coverage gap.
///
/// A false-positive resync is never *incorrect* — it costs one batched read — so
/// the policy is a **pure cost knob**, not a correctness lever.
///
/// [`Slots`]: TrackingPolicy::Slots
/// [`WholeAccount`]: TrackingPolicy::WholeAccount
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum TrackingPolicy {
    /// Sparse interest (e.g. WETH: a few balance slots). The root churns on
    /// nearly every block, so it is a noisy gate — this policy is **never**
    /// root-gated (spec Decision 3). Keep the enumerated slots fresh via decoders
    /// and cadence reconcile.
    Slots {
        /// The enumerated storage slots of interest.
        slots: Vec<U256>,
    },
    /// Whole economic state (e.g. a V2 pool). `root_moved ≈ my_state_changed`, so
    /// the root is a tight, cheap gate: probe each canonical block; on a move no
    /// decoder covered, emit a [`ReactiveReport::CoverageGap`] and schedule a
    /// [`ResyncReason::RootMoved`] repair.
    WholeAccount,
    /// Balance / nonce / code-hash only — resolved from the same `get_proof`
    /// response's account fields; no storage interest. Native balance/nonce
    /// changes do **not** move the storage root, so this policy compares the
    /// account fields directly across blocks rather than root-gating.
    Scalars,
}

/// How often the reactive root gate probes tracked accounts
/// ([`TrackingPolicy::WholeAccount`] / [`TrackingPolicy::Scalars`]; the
/// `Scalars` account-fields comparison rides the same firing).
///
/// `eth_getProof` is the slowest read this crate issues, so per-block probing
/// is never the default. Skipping blocks is safe by construction: the gate
/// diffs `root_now` against its **persisted baseline**, never
/// block-over-block, so a move in any skipped block is still visible at the
/// next firing — cadence trades detection lag (at most `n − 1` blocks) for
/// cost, never eventual detection. The decoder-touched set accumulates across
/// skipped blocks and drains per firing, so a covered write in a skipped
/// block never false-positives as a [`ReactiveReport::CoverageGap`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum RootGateCadence {
    /// Probe at most once every `n` canonical blocks (the first canonical
    /// block ever seen always fires, so baseline adoption does not wait a
    /// full window). `EveryNBlocks(1)` is per-block probing.
    EveryNBlocks(NonZeroU64),
    /// Root gate off: coverage gaps surface only via decoders + freshness.
    Disabled,
}

impl RootGateCadence {
    /// Probe at most once every `n` canonical blocks, clamping `0` to `1`.
    pub fn every_n_blocks(n: u64) -> Self {
        Self::EveryNBlocks(NonZeroU64::new(n.max(1)).expect("clamped to at least 1"))
    }
}

impl Default for RootGateCadence {
    /// Every 16 canonical blocks — ~3.2 min worst-case detection lag on
    /// mainnet for a 16× probe-cost cut. Fast-block chains should *raise*
    /// `n`, not lower it.
    fn default() -> Self {
        Self::every_n_blocks(16)
    }
}

/// Per-account baseline held by the root gate: the last observed on-chain root
/// and account fields, plus the block they were observed at.
///
/// The gate diffs the on-chain root **across time** (never local-vs-chain, per
/// spec §6): it persists the *observed* root as a baseline and compares
/// `root_now` to it. This is a currency gate, not a completeness gate.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
struct TrackedRoot {
    last_root: B256,
    last_block: u64,
    balance: U256,
    nonce: u64,
    code_hash: B256,
}

/// Request for authoritative state repair.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ResyncRequest {
    /// Resync id.
    pub id: ResyncId,
    /// Reason for the request.
    pub reason: ResyncReason,
    /// Block selection for the read.
    pub block: ResyncBlock,
    /// Targets to resync.
    pub targets: Vec<ResyncTarget>,
    /// Scheduling priority.
    pub priority: ResyncPriority,
}

/// Resync id.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct ResyncId(String);

impl ResyncId {
    /// Create a resync id.
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }
}

/// Reason for a resync request.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum ResyncReason {
    /// Handler requested repair.
    HandlerRequested,
    /// State effect could not be applied completely.
    SkippedStateEffect,
    /// A missed block range was detected; caller-scheduled repair.
    ///
    /// The runtime does not fabricate a targetless [`ResyncRequest`] for a missed
    /// range (there are no known targets to resync). This reason is provided so a
    /// caller building its own repair in response to a
    /// [`ReactiveReport::MissedBlockRange`] can attribute it.
    MissedBlockRange,
    /// A tracked account's storage root moved with no covering decoder.
    ///
    /// Emitted by the per-block root gate (Phase-8 step 4). A
    /// [`WholeAccount`](TrackingPolicy::WholeAccount)-tracked account's
    /// `storageHash` moved between the adopted baseline and the current canonical
    /// block, yet no decoder wrote that account during the block — a coverage gap.
    /// The gate schedules a resync with this reason to re-read the account
    /// authoritatively and self-heal the blind spot. Also used for the
    /// [`Scalars`](TrackingPolicy::Scalars) account-field freshness path.
    RootMoved,
    /// Caller-defined reason.
    Custom(String),
}

/// Block target for a resync.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum ResyncBlock {
    /// Latest block.
    Latest,
    /// Current provider pre-confirmation state.
    Pending,
    /// Safe head.
    Safe,
    /// Finalized head.
    Finalized,
    /// Block number.
    Number(u64),
    /// Block hash and number.
    Hash {
        /// Block number.
        number: u64,
        /// Block hash.
        hash: B256,
        /// Require the hash to still be canonical.
        require_canonical: bool,
    },
}

/// State target for a resync.
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum ResyncTarget {
    /// One storage slot.
    StorageSlot {
        /// Contract address.
        address: Address,
        /// Storage slot.
        slot: U256,
    },
    /// Multiple storage slots on one contract.
    StorageSlots {
        /// Contract address.
        address: Address,
        /// Storage slots.
        slots: Vec<U256>,
    },
    /// Account fields.
    Account {
        /// Account address.
        address: Address,
        /// Fields to resync.
        fields: AccountFieldMask,
    },
}

/// Account fields requested by a resync.
#[derive(
    Clone, Copy, Debug, Default, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize,
)]
pub struct AccountFieldMask {
    /// Balance field.
    pub balance: bool,
    /// Nonce field.
    pub nonce: bool,
    /// Code field.
    pub code: bool,
}

/// Resync priority.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    PartialEq,
    Eq,
    Hash,
    PartialOrd,
    Ord,
    serde::Serialize,
    serde::Deserialize,
)]
pub enum ResyncPriority {
    /// Low priority.
    Low,
    /// Normal priority.
    #[default]
    Normal,
    /// High priority.
    High,
}

/// Rich invalidation request lowered to [`StateUpdate::Purge`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct InvalidationRequest {
    /// Purge scope.
    pub scope: PurgeScope,
    /// Address to purge.
    pub address: Address,
    /// Reason for reporting.
    pub reason: InvalidationReason,
}

/// Invalidation reason.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum InvalidationReason {
    /// Handler requested invalidation.
    HandlerRequested,
    /// Reorg invalidation.
    Reorg,
    /// Caller-defined reason.
    Custom(String),
}

/// Speculative signal emitted by handlers.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SpeculativeRequest {
    /// Speculative request id.
    pub id: SpeculativeId,
    /// Input that triggered the request.
    pub input_ref: InputRef,
    /// Labels for downstream routing.
    pub labels: Vec<ReportTag>,
}

/// Speculative request id.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct SpeculativeId(String);

impl SpeculativeId {
    /// Create a speculative id.
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }
}

/// Configuration for [`ReactiveRuntime`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReactiveConfig {
    /// Hook backpressure policy. **Reserved — currently has no effect.** Hook
    /// dispatch is synchronous today (every report is delivered to every hook in
    /// order), so this field is a no-op placeholder for a future async dispatcher.
    /// Setting it to anything other than the default does not change behavior.
    pub hook_backpressure: HookBackpressure,
    /// Reorg journal depth: the number of recent canonical blocks whose effects
    /// are journaled for rollback. This is **load-bearing** for reorg recovery:
    /// only blocks still resident in the journal can be recovered. A reorg deeper
    /// than `journal_depth` recovers the blocks still in the journal and leaves
    /// the aged-out blocks' effects in place — they are **neither rolled back nor
    /// purged**, so the freshness/validation loop is the only backstop for that
    /// span. `0` disables journaling entirely: no reorg is rolled back or purged.
    ///
    /// Set `journal_depth` to exceed the deepest reorg you intend to recover
    /// precisely. When a reorg references a block that is no longer in the journal,
    /// the runtime emits a `tracing::warn!` so the under-recovery is observable
    /// rather than silent. Checkpointed engine ingestion is stricter: explicit
    /// reorgs, implicit parent replacements, and removed/reorged records whose
    /// rollback proof falls outside the retained effect journal are rejected
    /// before mutation, durable save, or acknowledgement. Align this depth with
    /// the complete reorg horizon promised by the subscriber.
    pub journal_depth: usize,
}

impl Default for ReactiveConfig {
    fn default() -> Self {
        Self {
            hook_backpressure: HookBackpressure::Block,
            journal_depth: 64,
        }
    }
}

/// Hook backpressure policy.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum HookBackpressure {
    /// Block the producer until hooks are accepted.
    Block,
    /// Drop the newest report under pressure.
    DropNewest,
    /// Drop the oldest report under pressure.
    DropOldest,
    /// Return an error under pressure.
    Error,
}

/// Queryable coarse health of the reactive cache.
///
/// The runtime starts [`Healthy`](CacheHealth::Healthy) and transitions to a
/// degraded or unhealthy state when it detects that its recovery guarantees no
/// longer hold (for example a reorg that runs deeper than the journal, so some
/// dropped effects are neither rolled back nor purged). Later waves report
/// missed-range and coverage-gap conditions into the same state machine.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum CacheHealth {
    /// All recovery guarantees hold; the cache is fully self-consistent.
    #[default]
    Healthy,
    /// A recoverable inconsistency was detected (for example under-recovered
    /// reorg effects); `since_block` records the block that triggered the
    /// transition.
    Degraded {
        /// Block number at which the degradation was first observed.
        since_block: u64,
    },
    /// A more serious inconsistency was detected; `since_block` records the
    /// block that triggered the transition.
    Unhealthy {
        /// Block number at which the unhealthy condition was first observed.
        since_block: u64,
    },
}

/// Point-in-time copy of the reactive runtime's observability counters.
///
/// Returned by [`ReactiveRuntime::metrics`]. Each field is a monotonically
/// increasing count over the lifetime of the runtime. Counters wired by later
/// waves (missed-range detection, storage-hash coverage gaps, stale-verdict
/// tracking) remain zero until those waves land.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub struct CacheMetricsSnapshot {
    /// Reorgs that ran deeper than the journal, so aged-out effects could not be
    /// rolled back or purged.
    pub deep_reorgs: u64,
    /// Reorgs for which a [`ReorgReport`] recovery ran (including deep reorgs).
    pub reorgs_recovered: u64,
    /// Storage resync targets considered by the resync execution pass.
    pub resync_requests: u64,
    /// Storage resync targets that could not be fetched or applied.
    pub resync_failures: u64,
    /// Ranges of blocks the runtime detected it did not observe (reserved).
    pub missed_ranges: u64,
    /// Storage-hash coverage gaps detected (reserved).
    pub coverage_gaps: u64,
    /// Pending-source inputs that attempted a canonical cache effect.
    pub pending_contamination: u64,
    /// Verdicts served past their freshness horizon (reserved).
    pub stale_verdicts: u64,
}

/// Internal atomic-backed counters mirrored by [`CacheMetricsSnapshot`].
///
/// Fields are [`AtomicU64`] so counters can be incremented behind a shared
/// reference; [`ReactiveRuntime::metrics`] loads each with [`Ordering::Relaxed`]
/// into a plain [`CacheMetricsSnapshot`].
#[derive(Debug, Default)]
struct CacheMetrics {
    deep_reorgs: AtomicU64,
    reorgs_recovered: AtomicU64,
    resync_requests: AtomicU64,
    resync_failures: AtomicU64,
    missed_ranges: AtomicU64,
    coverage_gaps: AtomicU64,
    pending_contamination: AtomicU64,
    stale_verdicts: AtomicU64,
}

impl CacheMetrics {
    fn snapshot(&self) -> CacheMetricsSnapshot {
        CacheMetricsSnapshot {
            deep_reorgs: self.deep_reorgs.load(Ordering::Relaxed),
            reorgs_recovered: self.reorgs_recovered.load(Ordering::Relaxed),
            resync_requests: self.resync_requests.load(Ordering::Relaxed),
            resync_failures: self.resync_failures.load(Ordering::Relaxed),
            missed_ranges: self.missed_ranges.load(Ordering::Relaxed),
            coverage_gaps: self.coverage_gaps.load(Ordering::Relaxed),
            pending_contamination: self.pending_contamination.load(Ordering::Relaxed),
            stale_verdicts: self.stale_verdicts.load(Ordering::Relaxed),
        }
    }

    fn restore(&self, snapshot: CacheMetricsSnapshot) {
        self.deep_reorgs
            .store(snapshot.deep_reorgs, Ordering::Relaxed);
        self.reorgs_recovered
            .store(snapshot.reorgs_recovered, Ordering::Relaxed);
        self.resync_requests
            .store(snapshot.resync_requests, Ordering::Relaxed);
        self.resync_failures
            .store(snapshot.resync_failures, Ordering::Relaxed);
        self.missed_ranges
            .store(snapshot.missed_ranges, Ordering::Relaxed);
        self.coverage_gaps
            .store(snapshot.coverage_gaps, Ordering::Relaxed);
        self.pending_contamination
            .store(snapshot.pending_contamination, Ordering::Relaxed);
        self.stale_verdicts
            .store(snapshot.stale_verdicts, Ordering::Relaxed);
    }
}

/// Runtime report.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum ReactiveReport<N: Network = Ethereum> {
    /// Input was accepted after deduplication.
    Input(InputReport<N>),
    /// Handlers produced outcomes.
    Decoded(DecodedReport<N>),
    /// Direct state effects were applied.
    Applied(AppliedReport<N>),
    /// Resync request was scheduled or completed.
    Resynced(ResyncReport),
    /// Block-level processing completed.
    BlockCommitted(BlockReport<N>),
    /// Reorg processing report.
    Reorg(ReorgReport<N>),
    /// Ordered source control accepted by the runtime.
    ChainControl(ChainControlReport),
    /// A forward gap in the canonical block sequence was detected: blocks between
    /// the last-seen head and an arriving block were never observed.
    MissedBlockRange(MissedRangeReport<N>),
    /// Cache health transitioned between states.
    Health(HealthReport<N>),
    /// A tracked account's storage root moved with no covering decoder — a
    /// coverage gap the per-block root gate detected (Phase-8 step 4).
    CoverageGap(CoverageGapReport<N>),
    /// Runtime or handler error.
    Error(ReactiveErrorReport<N>),
}

/// Report emitted after an ordered source control is accepted.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ChainControlReport {
    /// Control in its original delivery order.
    pub control: ChainControl,
}

/// Input acceptance report.
#[derive(Clone, Debug)]
pub struct InputReport<N: Network = Ethereum> {
    /// Input reference.
    pub input_ref: InputRef,
    /// Input context.
    pub context: ReactiveContext,
    /// Provider session that originated the input, when known.
    pub provider: Option<ProviderRef>,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Decoding report.
#[derive(Clone, Debug)]
pub struct DecodedReport<N: Network = Ethereum> {
    /// Input reference.
    pub input_ref: InputRef,
    /// Handler ids that matched the input.
    pub handler_ids: Vec<HandlerId>,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Applied state report.
#[derive(Clone, Debug)]
pub struct AppliedReport<N: Network = Ethereum> {
    /// Input reference.
    pub input_ref: InputRef,
    /// Handler that produced the applied effects.
    pub handler_id: HandlerId,
    /// State effect quality.
    pub quality: StateEffectQuality,
    /// Labels emitted by the handler.
    pub tags: Vec<ReportTag>,
    /// Merged state diff from applied updates and invalidations.
    pub diff: StateDiff,
    /// State updates applied through the cache.
    pub state_updates: Vec<StateUpdate>,
    /// Invalidation requests lowered to purge updates.
    pub invalidations: Vec<InvalidationRequest>,
    /// Resync requests surfaced for a scheduler.
    pub resyncs: Vec<ResyncRequest>,
    /// Speculative requests surfaced for downstream users.
    pub speculative: Vec<SpeculativeRequest>,
    /// Hook signals emitted by the handler.
    pub hook_signals: Vec<HookSignal>,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Report of the storage resync requests executed during an ingest cycle: the
/// requests considered, the authoritative updates built from successful fetches
/// (and their applied diff), and any targets that could not be resynced.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ResyncReport {
    /// Requests considered by the resync execution pass.
    pub requested: Vec<ResyncRequest>,
    /// Authoritative state updates built from successful resync fetches.
    pub state_updates: Vec<StateUpdate>,
    /// Diff returned by applying [`state_updates`](Self::state_updates).
    pub diff: StateDiff,
    /// Targets that could not be resynced.
    pub failed: Vec<ResyncFailure>,
}

/// One resync target that could not be fetched or applied.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ResyncFailure {
    /// Request that produced the failed target.
    pub request_id: ResyncId,
    /// Block selection used for the failed target.
    pub block: ResyncBlock,
    /// Target that could not be resynced.
    pub target: ResyncTarget,
    /// Stable failure classification for retry policy and metrics.
    pub kind: ResyncFailureKind,
    /// Human-readable failure reason.
    pub message: String,
}

/// Stable classification for a failed resync target.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ResyncFailureKind {
    /// A storage target could not be fetched because no storage batch fetcher is configured.
    MissingStorageFetcher,
    /// The storage batch fetcher returned an error for the requested slot.
    StorageFetchFailed,
    /// The storage batch fetcher did not return a result for the requested slot.
    StorageFetchOmitted,
    /// An account target could not be fetched because no account proof fetcher is configured.
    MissingAccountFetcher,
    /// The account proof fetcher returned an error for the requested address.
    AccountFetchFailed,
    /// The account proof fetcher did not return a result for the requested address.
    AccountFetchOmitted,
}

/// Block processing report.
#[derive(Clone, Debug)]
pub struct BlockReport<N: Network = Ethereum> {
    /// Block reference, when known.
    pub block: Option<BlockRef>,
    /// Input references committed for the block.
    pub inputs: Vec<InputRef>,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Report of a detected reorg and the recovery it performed: the dropped
/// block(s) and inputs, the exact rollback updates applied for reversible dropped
/// effects, the conservative purge updates for irreversible ones, the canceled
/// hash-pinned resyncs, and why recovery ran.
///
/// Recovery only covers blocks still resident in the journal. If a reorg runs
/// deeper than [`ReactiveConfig::journal_depth`], the aged-out blocks do not
/// appear here and their effects are neither rolled back nor purged (the runtime
/// logs a `tracing::warn!` in that case); the freshness/validation loop is the
/// backstop for that span. Checkpointed engine ingestion rejects explicit,
/// implicit-parent, and removed-log recovery outside the retained journal
/// instead of producing and durably acknowledging a partial report.
/// Non-checkpointed ingestion still emits this report when no journal entry was
/// recoverable; in that case `dropped` identifies the signal/head when known,
/// while `dropped_blocks` and rollback effects are empty.
#[derive(Clone, Debug)]
pub struct ReorgReport<N: Network = Ethereum> {
    /// First dropped block, when known.
    pub dropped: Option<BlockRef>,
    /// Blocks dropped from the journal, in ascending journal order.
    pub dropped_blocks: Vec<BlockRef>,
    /// Input references that belonged to dropped blocks.
    pub dropped_inputs: Vec<InputRef>,
    /// Exact rollback updates applied for reversible dropped effects.
    pub rollback_updates: Vec<StateUpdate>,
    /// Diff returned by applying [`rollback_updates`](Self::rollback_updates).
    pub rollback_diff: StateDiff,
    /// Conservative purge updates applied for irreversible dropped effects.
    pub purge_updates: Vec<StateUpdate>,
    /// Diff returned by applying [`purge_updates`](Self::purge_updates).
    pub purge_diff: StateDiff,
    /// Hash-pinned pending resync requests canceled because their block was dropped.
    pub canceled_resyncs: Vec<ResyncRequest>,
    /// Reorg trigger.
    pub reason: ReorgReason,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Reason reorg recovery ran.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum ReorgReason {
    /// A provider emitted an Alloy removed log.
    RemovedLog,
    /// The input context explicitly marked an input as reorged.
    ReorgedInput,
    /// A canonical block did not connect to the journaled head.
    ParentMismatch,
    /// A subscriber delivered an explicit canonical branch transition.
    Explicit,
}

/// Report of a forward gap in the canonical block sequence: an arriving block
/// whose number is more than one past the last-seen head, so the blocks in
/// between were never observed (for example during a subscription disconnect).
///
/// The arriving block is still accepted and applied — the chain extends — so this
/// report only makes the skipped span observable; it does not drop the block. The
/// span `from..=to` is inclusive of both endpoints.
#[derive(Clone, Debug)]
pub struct MissedRangeReport<N: Network = Ethereum> {
    /// First skipped block (`last-seen block number + 1`).
    pub from: u64,
    /// Last skipped block (`arriving block number - 1`).
    pub to: u64,
    /// The arriving block's number.
    pub block: u64,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Report of a [`CacheHealth`] transition, emitted into the ingest cycle that
/// caused it and delivered to hooks through the normal dispatch path.
#[derive(Clone, Debug)]
pub struct HealthReport<N: Network = Ethereum> {
    /// Health state before the transition.
    pub from: CacheHealth,
    /// Health state after the transition.
    pub to: CacheHealth,
    /// Block number associated with the transition, when known.
    pub block: Option<u64>,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Report that a tracked account's storage root moved on a canonical block that
/// no decoder covered — a coverage gap surfaced by the per-block root gate
/// (Phase-8 step 4).
///
/// An account's `storageHash` is a collision-resistant commitment over all of its
/// storage, so a moved root proves *something* under the account changed. When
/// that account is [`WholeAccount`](TrackingPolicy::WholeAccount)-tracked and the
/// batch's touched-address set does not include it, the change arrived through a
/// path no decoder observed. The runtime emits this report (delivered through the
/// normal dispatch path so [`ReactiveHook::on_report`] observers see it),
/// increments [`CacheMetricsSnapshot::coverage_gaps`], and schedules a
/// [`ResyncReason::RootMoved`] repair to re-read the account authoritatively.
#[derive(Clone, Debug)]
pub struct CoverageGapReport<N: Network = Ethereum> {
    /// The tracked account whose root moved with no covering decoder.
    pub address: Address,
    /// The canonical block number at which the gap was observed.
    pub block: u64,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Report of a non-fatal error surfaced during an ingest cycle, with the
/// associated input (when known) and a human-readable message.
#[derive(Clone, Debug)]
pub struct ReactiveErrorReport<N: Network = Ethereum> {
    /// Input associated with the error, when known.
    pub input_ref: Option<InputRef>,
    /// Error message.
    pub message: String,
    /// Network marker.
    pub _network: PhantomData<N>,
}

/// Batch report returned by [`ReactiveRuntime::ingest_batch`] and
/// [`ReactiveRuntime::ingest_batch_with_resync`].
#[derive(Clone, Debug)]
pub struct ReactiveBatchReport<N: Network = Ethereum> {
    /// Applied reports in commit order.
    pub applied: Vec<AppliedReport<N>>,
    /// Resync requests surfaced during the batch.
    pub resyncs: Vec<ResyncRequest>,
    /// Speculative requests surfaced during the batch.
    pub speculative: Vec<SpeculativeRequest>,
    /// Hook reports dispatched after mutation phases.
    pub reports: Vec<Arc<ReactiveReport<N>>>,
}

impl<N: Network> Default for ReactiveBatchReport<N> {
    fn default() -> Self {
        Self {
            applied: Vec::new(),
            resyncs: Vec::new(),
            speculative: Vec::new(),
            reports: Vec::new(),
        }
    }
}

/// Error returned by a handler.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct HandlerError {
    message: String,
}

impl HandlerError {
    /// Create a handler error from a message.
    pub fn new(message: impl Into<String>) -> Self {
        Self {
            message: message.into(),
        }
    }
}

impl fmt::Display for HandlerError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.message.fmt(f)
    }
}

impl std::error::Error for HandlerError {}

impl From<String> for HandlerError {
    fn from(message: String) -> Self {
        Self::new(message)
    }
}

impl From<&str> for HandlerError {
    fn from(message: &str) -> Self {
        Self::new(message)
    }
}

/// Runtime error.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReactiveError {
    /// Handler returned an error.
    #[error("handler `{handler_id}` failed: {source}")]
    HandlerFailed {
        /// Handler id.
        handler_id: HandlerId,
        /// Handler error.
        source: HandlerError,
    },
    /// Multiple handlers emitted incompatible absolute writes for one input.
    #[error(
        "conflicting effects for input {input_ref:?} on target {target:?}: `{first}` vs `{second}`"
    )]
    ConflictingEffects {
        /// Input reference.
        input_ref: Box<InputRef>,
        /// Conflicting target.
        target: Box<EffectTarget>,
        /// First handler id.
        first: HandlerId,
        /// Second handler id.
        second: HandlerId,
    },
    /// Pending inputs attempted to mutate canonical cache state.
    #[error(
        "pending input {input_ref:?} emitted invalid canonical effect `{effect_kind}` from `{handler_id}`"
    )]
    InvalidPendingEffect {
        /// Input reference.
        input_ref: Box<InputRef>,
        /// Handler id.
        handler_id: HandlerId,
        /// Effect kind.
        effect_kind: &'static str,
    },
    /// A subscriber supplied payload metadata that is incomplete or
    /// contradicts the accompanying context.
    #[error("invalid reactive input record: {message}")]
    InvalidInputRecord {
        /// Human-readable invariant violation.
        message: String,
    },
    /// A source delivered a contradictory chain-lifecycle transition.
    #[error("invalid chain control: {message}")]
    InvalidChainControl {
        /// Human-readable invariant violation.
        message: String,
    },
    /// Owner-scoped catch-up would mutate a historical block for which the
    /// runtime has no rollback journal entry.
    #[error(
        "owner catch-up block {number} {hash} is outside the retained canonical rollback journal"
    )]
    OwnerCatchupOutsideJournal {
        /// Catch-up block number.
        number: u64,
        /// Catch-up block hash.
        hash: B256,
    },
    /// Registration error.
    #[error(transparent)]
    Register(#[from] RegisterError),
}

/// Handler registration error.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum RegisterError {
    /// Duplicate handler id.
    #[error("handler id `{0}` is already registered")]
    DuplicateHandler(HandlerId),
}

/// Error returned when [`ReactiveEngine`] cannot register a handler on both the
/// runtime and subscriber sides.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReactiveEngineRegisterError {
    /// Runtime registry rejected the handler.
    #[error(transparent)]
    Register(#[from] RegisterError),
    /// Subscriber rejected the handler's interests.
    #[error(transparent)]
    Subscriber(#[from] SubscriberError),
    /// Owner-only history was not constrained to one hash-certified block that
    /// remains in the runtime rollback journal.
    #[error(
        "owner backfill {start_block}..={end_block:?} must target exactly one hash-certified block in the retained rollback journal"
    )]
    BackfillOutsideJournal {
        /// First requested block.
        start_block: u64,
        /// Inclusive requested upper bound, if bounded.
        end_block: Option<u64>,
        /// Hash-certified anchor supplied by the caller, if any.
        retained_anchor: Option<BlockRef>,
    },
}

/// Error adopting an RPC snapshot as a runtime's canonical continuity
/// baseline.
#[derive(Clone, Debug, thiserror::Error, PartialEq, Eq)]
#[non_exhaustive]
pub enum ReactiveBaselineError {
    /// Runtime or engine delivery state already contains lifecycle work.
    #[error("cannot adopt a canonical baseline after reactive processing has started")]
    ActiveRuntime,
    /// An exact repeat is allowed, but the requested baseline conflicts with
    /// the previously adopted block.
    #[error(
        "canonical baseline conflicts with existing block {existing_number} {existing_hash} (requested {requested_number} {requested_hash})"
    )]
    ConflictingBaseline {
        /// Existing baseline number.
        existing_number: u64,
        /// Existing baseline hash.
        existing_hash: B256,
        /// Requested baseline number.
        requested_number: u64,
        /// Requested baseline hash.
        requested_hash: B256,
    },
    /// Typed baseline and cache identify different chains.
    #[error("baseline chain id {baseline_chain_id} does not match cache chain id {cache_chain_id}")]
    CacheChainMismatch {
        /// Chain declared by the baseline.
        baseline_chain_id: u64,
        /// Chain configured on the cache.
        cache_chain_id: u64,
    },
    /// The cache is not hash-pinned to the exact adopted canonical block.
    #[error("cache block selector is not canonically hash-pinned to baseline {number} {hash}")]
    CacheBlockMismatch {
        /// Expected baseline number.
        number: u64,
        /// Expected baseline hash.
        hash: B256,
    },
}

/// Error returned by [`ReactiveEngine`] helpers that combine subscriber polling
/// and runtime ingestion.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReactiveEngineError {
    /// Subscriber polling failed.
    #[error(transparent)]
    Subscriber(#[from] SubscriberError),
    /// Runtime ingestion failed.
    #[error(transparent)]
    Runtime(ReactiveError),
    /// Canonical cold-start baseline adoption failed.
    #[error(transparent)]
    Baseline(#[from] ReactiveBaselineError),
    /// Runtime ingestion succeeded, but its durable delivery acknowledgement
    /// did not commit. The subscriber may replay the batch.
    #[error("runtime ingestion succeeded but subscriber acknowledgement failed: {0}")]
    Acknowledgement(#[source] SubscriberError),
    /// Runtime ingestion succeeded, but the resulting cache state could not be
    /// durably checkpointed. The engine retains the commit in memory and must
    /// retry it before polling another batch.
    #[error("runtime ingestion succeeded but durable checkpoint commit failed: {0}")]
    Checkpoint(#[source] DurableCheckpointError),
    /// A checkpointed ingest had no canonical block to bind the state to.
    #[error("cannot durably checkpoint reactive state before observing a canonical block")]
    MissingCheckpointBlock,
    /// Speculative pre-confirmation state is intentionally excluded from
    /// canonical durable checkpoints.
    #[error("pre-confirmed Flashblock batches cannot be durably checkpointed")]
    PreconfirmationNotCheckpointable,
    /// Runtime rollback/finality state could not be encoded for the checkpoint.
    #[error("failed to encode durable reactive runtime state: {0}")]
    RuntimeCheckpoint(String),
    /// A crash-safe checkpoint commit is pending, so the engine cannot switch
    /// to ordinary acknowledgement ordering without first completing it.
    #[error("cannot use ordinary ingestion while a durable checkpoint commit is pending")]
    PendingCheckpointCommit,
    /// An ordinary delivery acknowledgement is pending, so the engine cannot
    /// switch to checkpointed ingestion and retroactively make it durable.
    #[error("cannot use checkpointed ingestion while an ordinary acknowledgement is pending")]
    PendingAcknowledgementCommit,
    /// A caller attempted to use a raw ingestion helper with subscriber-owned
    /// commit metadata. Only the combined polling helpers can preserve the
    /// required ingest-before-checkpoint-before-acknowledgement ordering.
    #[error(
        "raw engine ingestion cannot consume delivery tokens or subscriber checkpoints; use a combined next_ingest helper"
    )]
    UncommittedDeliveryMetadata,
    /// Subscriber and cache are bound to different chains.
    #[error(
        "subscriber chain id {subscriber_chain_id} does not match cache chain id {cache_chain_id}"
    )]
    SubscriberChainMismatch {
        /// Chain reported by the subscriber.
        subscriber_chain_id: u64,
        /// Chain configured on the cache.
        cache_chain_id: u64,
    },
    /// Crash-safe checkpoint APIs require durable replay/resume semantics.
    #[error("subscriber does not advertise durable replay support")]
    SubscriberNotDurable,
    /// A restored delivery token predates or otherwise lacks the core witness
    /// needed to prove that a replay carries the same delivery.
    #[error(
        "committed delivery token has no delivery witness; replay cannot be acknowledged safely"
    )]
    MissingReplayWitness,
    /// A source reused a committed token for different records, routing,
    /// controls, chain identity, or provider resume state.
    #[error("replayed delivery token does not match its committed delivery witness")]
    ReplayDeliveryMismatch,
    /// The stable delivery witness could not be encoded.
    #[error("failed to encode durable delivery witness: {0}")]
    DeliveryWitness(String),
    /// A tokened network-generic header/body cannot be witnessed completely
    /// without a source-supplied canonical wire commitment.
    #[error(
        "tokened block-header, full-block, or hydrated-transaction delivery requires an exact payload commitment"
    )]
    MissingPayloadCommitment,
    /// Cache state changed after a batch was staged for a checkpoint. Retrying
    /// would bind those unrelated mutations to the older delivery metadata.
    #[error(
        "cache changed while durable checkpoint commit was pending (staged generation {staged_generation}, current generation {current_generation})"
    )]
    PendingCheckpointCacheChanged {
        /// Generation immediately after the staged batch was ingested.
        staged_generation: u64,
        /// Generation observed when checkpoint commit was retried.
        current_generation: u64,
    },
    /// Checkpointed ingestion cannot durably acknowledge a reorg when the
    /// runtime no longer retains every potentially affected journal entry.
    #[error(
        "reorg after block {common_ancestor} exceeds the retained rollback journal (oldest retained block {oldest_journaled:?}, configured depth {journal_depth})"
    )]
    CheckpointReorgOutsideJournal {
        /// Last block shared by the old and replacement branches.
        common_ancestor: u64,
        /// Oldest retained effect-bearing journal block, if any.
        oldest_journaled: Option<u64>,
        /// Configured maximum journal entries.
        journal_depth: usize,
    },
    /// Owner-scoped catch-up would mutate a historical block for which the
    /// runtime has no rollback journal entry.
    #[error(
        "owner catch-up block {number} {hash} is outside the retained canonical rollback journal"
    )]
    OwnerCatchupOutsideJournal {
        /// Catch-up block number.
        number: u64,
        /// Catch-up block hash.
        hash: B256,
    },
}

impl From<ReactiveError> for ReactiveEngineError {
    fn from(error: ReactiveError) -> Self {
        match error {
            ReactiveError::OwnerCatchupOutsideJournal { number, hash } => {
                Self::OwnerCatchupOutsideJournal { number, hash }
            }
            error => Self::Runtime(error),
        }
    }
}

/// Error restoring a durable checkpoint anchor into an active runtime.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReactiveCheckpointRestoreError {
    /// A runtime with canonical journal state cannot be silently rewound.
    #[error("cannot restore a durable checkpoint into a runtime with canonical journal state")]
    ActiveRuntime,
    /// Stored runtime recovery bytes were malformed or unsupported.
    #[error("invalid durable reactive runtime state: {0}")]
    InvalidRuntimeCheckpoint(String),
    /// Checkpoint identity or cache restoration failed before activation.
    #[error(transparent)]
    Checkpoint(#[from] DurableCheckpointError),
    /// Subscriber rejected the restored durable cursor or canonical position.
    #[error("subscriber rejected durable resume position: {0}")]
    Subscriber(#[source] SubscriberError),
    /// Subscriber and checkpoint identities name different chains.
    #[error(
        "subscriber chain id {subscriber_chain_id} does not match checkpoint chain id {checkpoint_chain_id}"
    )]
    SubscriberChainMismatch {
        /// Chain reported by the subscriber.
        subscriber_chain_id: u64,
        /// Chain committed by the checkpoint identity.
        checkpoint_chain_id: u64,
    },
    /// Restoring event continuity requires a durable replay-capable subscriber.
    #[error("subscriber does not advertise durable replay support")]
    SubscriberNotDurable,
}

/// Result of one crash-safe subscriber ingest cycle.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum CheckpointedIngest<N: Network = Ethereum> {
    /// A new batch was ingested, durably checkpointed, and acknowledged.
    Applied(ReactiveBatchReport<N>),
    /// The checkpoint already contained this replayed delivery token, so the
    /// batch was acknowledged without applying its effects twice.
    ReplayAcknowledged,
}

/// Absolute write target used for conflict reports.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum EffectTarget {
    /// Storage slot target.
    StorageSlot {
        /// Contract address.
        address: Address,
        /// Storage slot.
        slot: U256,
    },
    /// Account balance target.
    AccountBalance {
        /// Account address.
        address: Address,
    },
    /// Account nonce target.
    AccountNonce {
        /// Account address.
        address: Address,
    },
    /// Account code target.
    AccountCode {
        /// Account address.
        address: Address,
    },
    /// Masked storage slot target.
    MaskedStorageSlot {
        /// Contract address.
        address: Address,
        /// Storage slot.
        slot: U256,
        /// Bit mask.
        mask: U256,
    },
}

#[derive(Clone, Debug, PartialEq, Eq)]
enum AbsoluteValue {
    U256(U256),
    U64(u64),
    Bytes(Bytes),
}

/// Reactive runtime.
pub struct ReactiveRuntime<N: Network = Ethereum> {
    registry: ReactiveRegistry<N>,
    hooks: Vec<Arc<dyn ReactiveHook<N>>>,
    config: ReactiveConfig,
    journal: VecDeque<BlockJournal<N>>,
    coverage_head: Option<BlockRef>,
    pending_resyncs: Vec<ResyncRequest>,
    health: CacheHealth,
    safe_head: Option<BlockRef>,
    finalized_head: Option<BlockRef>,
    metrics: CacheMetrics,
    /// Opt-in freshness registry the runtime stamps for canonical event writes.
    ///
    /// `None` by default (behavior unchanged); populated by
    /// [`enable_freshness_stamping`](Self::enable_freshness_stamping). When
    /// present, applying a canonical handler storage-slot effect stamps the
    /// touched `(address, slot)` as [`Validity::ValidThrough`](crate::freshness::Validity::ValidThrough)`(N)`
    /// so event-maintained slots stop being needlessly re-verified while aging to
    /// volatile once the clock passes `N`.
    freshness: Option<FreshnessRegistry>,
    /// Per-account tracking registry consulted by the per-block root gate
    /// (Phase-8 step 4). Empty by default; populated by
    /// [`track_account`](Self::track_account). When empty the gate is a no-op.
    tracking: HashMap<Address, TrackingPolicy>,
    /// Per-account root/field baselines the gate diffs against across blocks.
    /// Adopted on first probe and re-adopted on every observed move.
    tracked_roots: HashMap<Address, TrackedRoot>,
    /// How often the root gate fires (§6.2); see [`RootGateCadence`].
    root_gate_cadence: RootGateCadence,
    /// Canonical block of the last root-gate firing. `None` until the first
    /// firing (which happens at the first canonical block ever seen, so
    /// baseline adoption never waits a full cadence window).
    last_gate_block: Option<u64>,
    /// Union of decoder-touched addresses since the last root-gate firing,
    /// drained when it fires. Under cadence the gap rule "root moved ∧ addr ∉
    /// touched" must judge against every covered write in the window, or a
    /// decoder-covered write in a skipped block would false-positive as a
    /// [`ReactiveReport::CoverageGap`].
    touched_since_gate: HashSet<Address>,
    /// Disposable pre-confirmation branch layered over the canonical cache.
    /// This is deliberately omitted from durable runtime checkpoints.
    preconfirmed_branch: Option<PreconfirmedBranch>,
}

#[derive(Clone)]
struct PreconfirmedBranch {
    flashblock: FlashblockRef,
    canonical_cache: EvmCacheStateSnapshot,
}

#[derive(Clone, Debug)]
struct BlockJournal<N: Network = Ethereum> {
    block: BlockRef,
    inputs: Vec<InputRef>,
    applied: Vec<AppliedReport<N>>,
    handler_ids: Vec<HandlerId>,
    resynced: Vec<ResyncReport>,
    rollback_diffs: Vec<StateDiff>,
}

const DURABLE_RUNTIME_CHECKPOINT_VERSION: u32 = 3;

#[derive(serde::Serialize, serde::Deserialize)]
struct DurableRuntimeCheckpoint {
    version: u32,
    safe_head: Option<BlockRef>,
    finalized_head: Option<BlockRef>,
    health: CacheHealth,
    pending_resyncs: Vec<ResyncRequest>,
    coverage_head: Option<BlockRef>,
    journal: Vec<DurableBlockJournal>,
    freshness: Option<FreshnessRegistry>,
    tracking: HashMap<Address, TrackingPolicy>,
    tracked_roots: HashMap<Address, TrackedRoot>,
    root_gate_cadence: RootGateCadence,
    last_gate_block: Option<u64>,
    touched_since_gate: HashSet<Address>,
    metrics: CacheMetricsSnapshot,
}

#[derive(serde::Serialize, serde::Deserialize)]
struct DurableBlockJournal {
    block: BlockRef,
    handler_ids: Vec<HandlerId>,
    rollback_diffs: Vec<StateDiff>,
}

struct DurableRuntimeRestorePlan {
    checkpoint: Option<DurableRuntimeCheckpoint>,
    fallback_history: Vec<BlockRef>,
}

impl DurableRuntimeRestorePlan {
    fn canonical_history(&self) -> Vec<BlockRef> {
        self.checkpoint.as_ref().map_or_else(
            || self.fallback_history.clone(),
            |checkpoint| checkpoint.journal.iter().map(|entry| entry.block).collect(),
        )
    }
}

#[derive(Clone)]
struct ReactiveRuntimeState<N: Network> {
    journal: VecDeque<BlockJournal<N>>,
    coverage_head: Option<BlockRef>,
    pending_resyncs: Vec<ResyncRequest>,
    health: CacheHealth,
    safe_head: Option<BlockRef>,
    finalized_head: Option<BlockRef>,
    freshness: Option<FreshnessRegistry>,
    tracking: HashMap<Address, TrackingPolicy>,
    tracked_roots: HashMap<Address, TrackedRoot>,
    root_gate_cadence: RootGateCadence,
    last_gate_block: Option<u64>,
    touched_since_gate: HashSet<Address>,
    metrics: CacheMetricsSnapshot,
}

#[derive(Clone)]
struct ChainControlState {
    journal_invalidated_from: Option<u64>,
    resolved_canonical_blocks: HashMap<(u64, B256), BlockRef>,
}

/// Canonical branch fragments already rolled back by the current atomic batch.
///
/// Providers commonly emit one removed notification per log after one signal
/// has already drained the complete dropped block (and every retained
/// descendant). Explicit reorg controls can be followed by the same redundant
/// lifecycle records. Exact identities decide whether removal recovery is
/// redundant; numeric spans are retained only as same-batch proof for a
/// parentless replacement after those exact journal entries were drained.
#[derive(Default)]
struct BatchDroppedCanonical {
    identities: HashSet<(u64, B256)>,
    implicit_spans: Vec<(u64, u64)>,
}

impl BatchDroppedCanonical {
    fn covers_implicit_number(&self, number: u64) -> bool {
        self.implicit_spans
            .iter()
            .any(|(from, through)| number >= *from && number <= *through)
    }

    fn contains(&self, block: &BlockRef) -> bool {
        self.identities.contains(&(block.number, block.hash))
    }

    fn record_identity(&mut self, block: &BlockRef) {
        self.identities.insert((block.number, block.hash));
    }

    fn record_explicit(&mut self, _common_ancestor: &BlockRef, old_tip: &BlockRef) {
        self.identities.insert((old_tip.number, old_tip.hash));
    }

    fn record_drained(&mut self, blocks: &[BlockRef]) {
        let Some(from) = blocks.iter().map(|block| block.number).min() else {
            return;
        };
        let through = blocks
            .iter()
            .map(|block| block.number)
            .max()
            .expect("a non-empty drained set has a maximum");
        self.implicit_spans.push((from, through));
        self.identities
            .extend(blocks.iter().map(|block| (block.number, block.hash)));
    }
}

/// Registry and router for provider-neutral reactive handlers.
///
/// The registry stores pure [`ReactiveHandler`]s in registration order, exposes
/// consolidated provider-side log filters for subscription setup, and routes
/// provider logs back to the exact matching log interests. Consolidated filters
/// may be safe supersets; [`Self::route_log`] always re-checks the original
/// [`LogInterest`] and its local matcher before returning a route.
pub struct ReactiveRegistry<N: Network = Ethereum> {
    handlers: BTreeMap<u128, RegisteredHandler<N>>,
    handler_positions: HashMap<HandlerId, u128>,
    next_handler_position: u128,
    indexed_log_handlers: HashMap<LogRouteKey, BTreeSet<u128>>,
    fallback_log_handlers: BTreeSet<u128>,
    data_slice_shapes: HashMap<(usize, usize), usize>,
}

struct RegisteredHandler<N: Network = Ethereum> {
    id: HandlerId,
    handler: Arc<dyn ReactiveHandler<N>>,
    interests: Vec<ReactiveInterest<N>>,
    has_log_interests: bool,
    log_route_index: Option<LogRouteIndex>,
}

impl<N: Network> Default for ReactiveRegistry<N> {
    fn default() -> Self {
        Self::new()
    }
}

impl<N: Network> ReactiveRegistry<N> {
    /// Create an empty registry.
    pub fn new() -> Self {
        Self {
            handlers: BTreeMap::new(),
            handler_positions: HashMap::new(),
            next_handler_position: 0,
            indexed_log_handlers: HashMap::new(),
            fallback_log_handlers: BTreeSet::new(),
            data_slice_shapes: HashMap::new(),
        }
    }

    /// Register a handler, preserving registration order.
    ///
    /// Duplicate handler ids are rejected with
    /// [`RegisterError::DuplicateHandler`].
    ///
    /// # Errors
    ///
    /// Returns [`RegisterError::DuplicateHandler`] when the id is already
    /// registered.
    pub fn register_handler(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
    ) -> Result<(), RegisterError> {
        let id = handler.id();
        if self.handler_positions.contains_key(&id) {
            return Err(RegisterError::DuplicateHandler(id));
        }
        let interests = handler.interests();
        self.insert_handler_prepared(id, handler, interests);
        Ok(())
    }

    fn insert_handler_prepared(
        &mut self,
        id: HandlerId,
        handler: Arc<dyn ReactiveHandler<N>>,
        interests: Vec<ReactiveInterest<N>>,
    ) {
        debug_assert!(!self.handler_positions.contains_key(&id));
        let has_log_interests = interests
            .iter()
            .any(|interest| matches!(interest, ReactiveInterest::Logs(_)));
        let log_route_index = handler.log_route_index();
        if self.next_handler_position == u128::MAX {
            self.compact_handler_positions();
        }
        let position = self.next_handler_position;
        self.next_handler_position += 1;
        self.handler_positions.insert(id.clone(), position);
        if let Some(index) = &log_route_index {
            for key in index.keys() {
                if let LogRouteKey::DataSlice { offset, value } = key {
                    *self
                        .data_slice_shapes
                        .entry((*offset, value.len()))
                        .or_default() += 1;
                }
                self.indexed_log_handlers
                    .entry(key.clone())
                    .or_default()
                    .insert(position);
            }
        } else if has_log_interests {
            self.fallback_log_handlers.insert(position);
        }
        self.handlers.insert(
            position,
            RegisteredHandler {
                id,
                handler,
                interests,
                has_log_interests,
                log_route_index,
            },
        );
    }

    /// Remove one handler by id, leaving all other handlers and interests intact.
    ///
    /// Returns the removed handler when the id was registered. Cache eviction is
    /// intentionally outside this API: unregistering stops future routing and
    /// decode for the handler only.
    pub fn unregister_handler(&mut self, id: &HandlerId) -> Option<Arc<dyn ReactiveHandler<N>>> {
        let position = self.handler_positions.remove(id)?;
        let registered = self.handlers.remove(&position)?;
        if let Some(index) = &registered.log_route_index {
            for key in index.keys() {
                let remove_bucket = self
                    .indexed_log_handlers
                    .get_mut(key)
                    .is_some_and(|owners| {
                        owners.remove(&position);
                        owners.is_empty()
                    });
                if remove_bucket {
                    self.indexed_log_handlers.remove(key);
                }
                if let LogRouteKey::DataSlice { offset, value } = key {
                    let shape = (*offset, value.len());
                    let remove_shape =
                        self.data_slice_shapes.get_mut(&shape).is_some_and(|count| {
                            *count -= 1;
                            *count == 0
                        });
                    if remove_shape {
                        self.data_slice_shapes.remove(&shape);
                    }
                }
            }
        } else {
            self.fallback_log_handlers.remove(&position);
        }
        Some(registered.handler)
    }

    /// Return true when `id` is currently registered.
    pub fn contains_handler(&self, id: &HandlerId) -> bool {
        self.handler_positions.contains_key(id)
    }

    /// Ids of all registered handlers, in registration (= routing) order.
    pub fn handler_ids(&self) -> Vec<HandlerId> {
        self.handlers
            .values()
            .map(|handler| handler.id.clone())
            .collect()
    }

    /// Borrow the interests owned by one handler.
    pub fn handler_interests(&self, id: &HandlerId) -> Option<&[ReactiveInterest<N>]> {
        self.handler_positions
            .get(id)
            .and_then(|position| self.handlers.get(position))
            .map(|registered| registered.interests.as_slice())
    }

    /// Return all registered interests in handler registration order.
    pub fn interests(&self) -> Vec<ReactiveInterest<N>> {
        self.handlers
            .values()
            .flat_map(|handler| handler.interests.clone())
            .collect()
    }

    /// Return consolidated provider-side log filters.
    ///
    /// Filters are emitted in deterministic first-registration order by
    /// compatible block option. Within each returned filter, address and topic
    /// sets are unioned independently, which can intentionally overfetch. Use
    /// [`Self::route_log`] to enforce the exact original [`LogInterest`]s.
    pub fn log_subscription_filters(&self) -> Vec<Filter> {
        let mut filters = Vec::new();
        for interest in self.log_interests() {
            merge_log_subscription_filter(&mut filters, &interest.provider_filter);
        }
        filters
    }

    /// Route a log to exact matching handler interests.
    ///
    /// Routes are returned in handler registration order. Each handler appears
    /// at most once for a log, using the first matching log interest declared by
    /// that handler.
    pub fn route_log(&self, log: &Log) -> Vec<ReactiveLogRoute> {
        self.log_handler_candidates(log)
            .into_iter()
            .filter_map(|handler| handler.route_log(log))
            .collect()
    }

    fn log_handler_candidates(&self, log: &Log) -> Vec<&RegisteredHandler<N>> {
        let mut indexed_positions = Vec::new();
        if let Some(indexed) = self
            .indexed_log_handlers
            .get(&LogRouteKey::Emitter(log.address()))
        {
            indexed_positions.extend(indexed.iter().copied());
        }
        for (index, value) in log.topics().iter().copied().enumerate() {
            if let Some(indexed) = self
                .indexed_log_handlers
                .get(&LogRouteKey::Topic { index, value })
            {
                indexed_positions.extend(indexed.iter().copied());
            }
        }
        let data = log.inner.data.data.as_ref();
        for &(offset, len) in self.data_slice_shapes.keys() {
            let Some(end) = offset.checked_add(len) else {
                continue;
            };
            let Some(value) = data.get(offset..end) else {
                continue;
            };
            if let Some(indexed) = self.indexed_log_handlers.get(&LogRouteKey::DataSlice {
                offset,
                value: value.to_vec(),
            }) {
                indexed_positions.extend(indexed.iter().copied());
            }
        }
        if indexed_positions.is_empty() {
            if self.fallback_log_handlers.is_empty() {
                return Vec::new();
            }
            if !self.indexed_log_handlers.is_empty() {
                return self
                    .fallback_log_handlers
                    .iter()
                    .filter_map(|position| self.handlers.get(position))
                    .collect();
            }
            return self
                .handlers
                .values()
                .filter(|handler| handler.has_log_interests && handler.log_route_index.is_none())
                .collect();
        }

        indexed_positions.extend(self.fallback_log_handlers.iter().copied());
        indexed_positions.sort_unstable();
        indexed_positions.dedup();
        indexed_positions
            .into_iter()
            .filter_map(|position| self.handlers.get(&position))
            .collect()
    }

    fn handlers(&self) -> impl Iterator<Item = &RegisteredHandler<N>> {
        self.handlers.values()
    }

    fn log_interests(&self) -> impl Iterator<Item = &LogInterest> {
        self.handlers.values().flat_map(|handler| {
            handler
                .interests
                .iter()
                .filter_map(|interest| match interest {
                    ReactiveInterest::Logs(interest) => Some(interest),
                    ReactiveInterest::Blocks(_) | ReactiveInterest::PendingTransactions(_) => None,
                })
        })
    }

    fn compact_handler_positions(&mut self) {
        let handlers = std::mem::take(&mut self.handlers);
        self.handler_positions.clear();
        self.indexed_log_handlers.clear();
        self.fallback_log_handlers.clear();
        self.data_slice_shapes.clear();

        for (position, (_, handler)) in handlers.into_iter().enumerate() {
            let position = position as u128;
            self.handler_positions.insert(handler.id.clone(), position);
            if let Some(index) = &handler.log_route_index {
                for key in index.keys() {
                    if let LogRouteKey::DataSlice { offset, value } = key {
                        *self
                            .data_slice_shapes
                            .entry((*offset, value.len()))
                            .or_default() += 1;
                    }
                    self.indexed_log_handlers
                        .entry(key.clone())
                        .or_default()
                        .insert(position);
                }
            } else if handler.has_log_interests {
                self.fallback_log_handlers.insert(position);
            }
            self.handlers.insert(position, handler);
        }
        self.next_handler_position = self.handlers.len() as u128;
    }
}

impl<N: Network> ReactiveRuntime<N> {
    /// Create an empty runtime.
    pub fn new(config: ReactiveConfig) -> Self {
        Self {
            registry: ReactiveRegistry::new(),
            hooks: Vec::new(),
            config,
            journal: VecDeque::new(),
            coverage_head: None,
            pending_resyncs: Vec::new(),
            health: CacheHealth::Healthy,
            safe_head: None,
            finalized_head: None,
            metrics: CacheMetrics::default(),
            freshness: None,
            tracking: HashMap::new(),
            tracked_roots: HashMap::new(),
            root_gate_cadence: RootGateCadence::default(),
            last_gate_block: None,
            touched_since_gate: HashSet::new(),
            preconfirmed_branch: None,
        }
    }

    fn checkpoint_state(&self) -> ReactiveRuntimeState<N> {
        ReactiveRuntimeState {
            journal: self.journal.clone(),
            coverage_head: self.coverage_head,
            pending_resyncs: self.pending_resyncs.clone(),
            health: self.health,
            safe_head: self.safe_head,
            finalized_head: self.finalized_head,
            freshness: self.freshness.clone(),
            tracking: self.tracking.clone(),
            tracked_roots: self.tracked_roots.clone(),
            root_gate_cadence: self.root_gate_cadence,
            last_gate_block: self.last_gate_block,
            touched_since_gate: self.touched_since_gate.clone(),
            metrics: self.metrics.snapshot(),
        }
    }

    fn is_pristine_for_checkpoint_restore(&self) -> bool {
        self.preconfirmed_branch.is_none()
            && self.journal.is_empty()
            && self.coverage_head.is_none()
            && self.pending_resyncs.is_empty()
            && self.health == CacheHealth::Healthy
            && self.safe_head.is_none()
            && self.finalized_head.is_none()
            && self.tracked_roots.is_empty()
            && self.last_gate_block.is_none()
            && self.touched_since_gate.is_empty()
            && self.metrics.snapshot() == CacheMetricsSnapshot::default()
    }

    fn adopted_baseline_only(&self) -> Option<BlockRef> {
        let baseline = self.coverage_head?;
        let journal_is_baseline_only = if self.config.journal_depth == 0 {
            self.journal.is_empty()
        } else {
            self.journal.len() == 1
                && self.journal.front().is_some_and(|entry| {
                    entry.block == baseline
                        && entry.inputs.is_empty()
                        && entry.applied.is_empty()
                        && entry.handler_ids.is_empty()
                        && entry.resynced.is_empty()
                        && entry.rollback_diffs.is_empty()
                })
        };
        (self.preconfirmed_branch.is_none()
            && journal_is_baseline_only
            && self.pending_resyncs.is_empty()
            && self.health == CacheHealth::Healthy
            && self.safe_head.is_none()
            && self.finalized_head.is_none()
            && self.tracked_roots.is_empty()
            && self.last_gate_block.is_none()
            && self.touched_since_gate.is_empty()
            && self.metrics.snapshot() == CacheMetricsSnapshot::default())
        .then_some(baseline)
    }

    fn restore_state(&mut self, state: ReactiveRuntimeState<N>) {
        self.journal = state.journal;
        self.coverage_head = state.coverage_head;
        self.pending_resyncs = state.pending_resyncs;
        self.health = state.health;
        self.safe_head = state.safe_head;
        self.finalized_head = state.finalized_head;
        self.freshness = state.freshness;
        self.tracking = state.tracking;
        self.tracked_roots = state.tracked_roots;
        self.root_gate_cadence = state.root_gate_cadence;
        self.last_gate_block = state.last_gate_block;
        self.touched_since_gate = state.touched_since_gate;
        self.metrics.restore(state.metrics);
    }

    fn restore_transaction_state(&mut self, state: ReactiveRuntimeState<N>) {
        // Metrics describe lifetime observations, including rejected attempts,
        // and are documented as monotonic. Roll back canonical/runtime state
        // without erasing the failure signal that caused the transaction to
        // abort.
        let metrics = self.metrics.snapshot();
        self.restore_state(state);
        self.metrics.restore(metrics);
    }

    fn durable_checkpoint_bytes(&self) -> Result<Vec<u8>, ReactiveEngineError> {
        let checkpoint = DurableRuntimeCheckpoint {
            version: DURABLE_RUNTIME_CHECKPOINT_VERSION,
            safe_head: self.safe_head,
            finalized_head: self.finalized_head,
            health: self.health,
            pending_resyncs: self.pending_resyncs.clone(),
            coverage_head: self.coverage_head,
            journal: self
                .journal
                .iter()
                .map(|entry| DurableBlockJournal {
                    block: entry.block,
                    handler_ids: entry.handler_ids.clone(),
                    rollback_diffs: entry.rollback_diffs.clone(),
                })
                .collect(),
            freshness: self.freshness.clone(),
            tracking: self.tracking.clone(),
            tracked_roots: self.tracked_roots.clone(),
            root_gate_cadence: self.root_gate_cadence,
            last_gate_block: self.last_gate_block,
            touched_since_gate: self.touched_since_gate.clone(),
            metrics: self.metrics.snapshot(),
        };
        bincode::serialize(&checkpoint)
            .map_err(|error| ReactiveEngineError::RuntimeCheckpoint(error.to_string()))
    }

    fn plan_durable_checkpoint_restore(
        &self,
        bytes: &[u8],
        expected_coverage: &BlockRef,
    ) -> Result<DurableRuntimeRestorePlan, ReactiveCheckpointRestoreError> {
        let mut cursor = std::io::Cursor::new(bytes);
        let mut checkpoint: DurableRuntimeCheckpoint = bincode::DefaultOptions::new()
            .with_fixint_encoding()
            .with_limit(bytes.len() as u64)
            .deserialize_from(&mut cursor)
            .map_err(|error| {
                ReactiveCheckpointRestoreError::InvalidRuntimeCheckpoint(error.to_string())
            })?;
        if cursor.position() != bytes.len() as u64 {
            return Err(ReactiveCheckpointRestoreError::InvalidRuntimeCheckpoint(
                "runtime checkpoint has trailing bytes".to_owned(),
            ));
        }
        if checkpoint.version != DURABLE_RUNTIME_CHECKPOINT_VERSION {
            return Err(ReactiveCheckpointRestoreError::InvalidRuntimeCheckpoint(
                format!(
                    "unsupported runtime checkpoint version {}",
                    checkpoint.version
                ),
            ));
        }
        self.validate_durable_runtime_checkpoint(&checkpoint, expected_coverage)?;

        let retained = self.config.journal_depth.min(checkpoint.journal.len());
        let discard = checkpoint.journal.len() - retained;
        checkpoint.journal.drain(..discard);
        Ok(DurableRuntimeRestorePlan {
            checkpoint: Some(checkpoint),
            fallback_history: Vec::new(),
        })
    }

    fn apply_durable_checkpoint_restore(&mut self, plan: DurableRuntimeRestorePlan) {
        let Some(checkpoint) = plan.checkpoint else {
            self.journal = plan
                .fallback_history
                .into_iter()
                .map(|block| BlockJournal {
                    block,
                    inputs: Vec::new(),
                    applied: Vec::new(),
                    handler_ids: Vec::new(),
                    resynced: Vec::new(),
                    rollback_diffs: Vec::new(),
                })
                .collect();
            return;
        };
        self.safe_head = checkpoint.safe_head;
        self.finalized_head = checkpoint.finalized_head;
        self.health = checkpoint.health;
        self.pending_resyncs = checkpoint.pending_resyncs;
        self.coverage_head = checkpoint.coverage_head;
        self.journal = checkpoint
            .journal
            .into_iter()
            .map(|entry| BlockJournal {
                block: entry.block,
                inputs: Vec::new(),
                applied: Vec::new(),
                handler_ids: entry.handler_ids,
                resynced: Vec::new(),
                rollback_diffs: entry.rollback_diffs,
            })
            .collect();
        self.freshness = checkpoint.freshness;
        self.tracking = checkpoint.tracking;
        self.tracked_roots = checkpoint.tracked_roots;
        self.root_gate_cadence = checkpoint.root_gate_cadence;
        self.last_gate_block = checkpoint.last_gate_block;
        self.touched_since_gate = checkpoint.touched_since_gate;
        self.metrics.restore(checkpoint.metrics);
    }

    fn validate_durable_runtime_checkpoint(
        &self,
        checkpoint: &DurableRuntimeCheckpoint,
        expected_coverage: &BlockRef,
    ) -> Result<(), ReactiveCheckpointRestoreError> {
        let invalid =
            |message: String| ReactiveCheckpointRestoreError::InvalidRuntimeCheckpoint(message);
        let Some(coverage) = checkpoint.coverage_head.as_ref() else {
            return Err(invalid(
                "runtime checkpoint is missing its canonical coverage head".into(),
            ));
        };
        if !optional_block_refs_are_compatible(Some(coverage), Some(expected_coverage)) {
            return Err(invalid(format!(
                "runtime coverage {}:{:?} conflicts with checkpoint metadata {}:{:?}",
                coverage.number, coverage.hash, expected_coverage.number, expected_coverage.hash
            )));
        }
        for (label, head) in [
            ("safe", checkpoint.safe_head.as_ref()),
            ("finalized", checkpoint.finalized_head.as_ref()),
        ] {
            let Some(head) = head else { continue };
            if head.number > coverage.number
                || (head.number == coverage.number && head.hash != coverage.hash)
            {
                return Err(invalid(format!(
                    "{label} head {}:{:?} lies beyond or conflicts with canonical coverage {}:{:?}",
                    head.number, head.hash, coverage.number, coverage.hash
                )));
            }
            if head.number.checked_add(1) == Some(coverage.number)
                && coverage
                    .parent_hash
                    .is_some_and(|parent| parent != head.hash)
            {
                return Err(invalid(format!(
                    "canonical coverage does not descend from adjacent {label} head"
                )));
            }
        }
        if let (Some(finalized), Some(safe)) = (
            checkpoint.finalized_head.as_ref(),
            checkpoint.safe_head.as_ref(),
        ) {
            if finalized.number > safe.number
                || (finalized.number == safe.number && finalized.hash != safe.hash)
            {
                return Err(invalid(
                    "finalized head is above or conflicts with the safe head".into(),
                ));
            }
            if finalized.number.checked_add(1) == Some(safe.number)
                && safe.parent_hash != Some(finalized.hash)
            {
                return Err(invalid(
                    "adjacent safe head does not descend from finalized head".into(),
                ));
            }
        }

        let mut previous: Option<&DurableBlockJournal> = None;
        for entry in &checkpoint.journal {
            if entry.block.number > coverage.number
                || (entry.block.number == coverage.number && entry.block.hash != coverage.hash)
            {
                return Err(invalid(format!(
                    "journal block {}:{:?} lies beyond or conflicts with canonical coverage",
                    entry.block.number, entry.block.hash
                )));
            }
            if let Some(previous) = previous {
                if entry.block.number <= previous.block.number {
                    return Err(invalid(
                        "runtime journal block numbers are not strictly increasing".into(),
                    ));
                }
                if previous.block.number.checked_add(1) == Some(entry.block.number)
                    && entry.block.parent_hash.is_some()
                    && entry.block.parent_hash != Some(previous.block.hash)
                {
                    return Err(invalid(
                        "adjacent runtime journal blocks are not parent-linked".into(),
                    ));
                }
            }
            for (label, head) in [
                ("safe", checkpoint.safe_head.as_ref()),
                ("finalized", checkpoint.finalized_head.as_ref()),
            ] {
                if let Some(head) = head
                    && head.number == entry.block.number
                    && !optional_block_refs_are_compatible(Some(head), Some(&entry.block))
                {
                    return Err(invalid(format!(
                        "{label} head conflicts with the retained journal at block {}",
                        head.number
                    )));
                }
            }
            let mut handler_ids = HashSet::new();
            if entry
                .handler_ids
                .iter()
                .any(|handler_id| !handler_ids.insert(handler_id))
            {
                return Err(invalid(
                    "runtime journal contains duplicate handler generation ids".into(),
                ));
            }
            previous = Some(entry);
        }
        if let Some(tail) = checkpoint.journal.last()
            && tail.block.number == coverage.number
            && !optional_block_refs_are_compatible(Some(&tail.block), Some(coverage))
        {
            return Err(invalid(format!(
                "runtime journal tail conflicts with canonical coverage at block {}",
                coverage.number
            )));
        }
        if let Some(tail) = checkpoint.journal.last()
            && tail.block.number.checked_add(1) == Some(coverage.number)
            && coverage
                .parent_hash
                .is_some_and(|parent_hash| parent_hash != tail.block.hash)
        {
            return Err(invalid(format!(
                "canonical coverage does not descend from adjacent runtime journal tail at block {}",
                tail.block.number
            )));
        }

        if let Some(last_gate_block) = checkpoint.last_gate_block {
            if last_gate_block > coverage.number {
                return Err(invalid(
                    "root-gate cursor lies beyond canonical coverage".into(),
                ));
            }
        } else if !checkpoint.tracked_roots.is_empty() {
            return Err(invalid(
                "root-gate baselines exist without a completed gate cursor".into(),
            ));
        }
        for (address, baseline) in &checkpoint.tracked_roots {
            let Some(policy) = checkpoint.tracking.get(address) else {
                return Err(invalid(
                    "root-gate baseline has no corresponding tracking policy".into(),
                ));
            };
            if matches!(policy, TrackingPolicy::Slots { .. }) {
                return Err(invalid(
                    "slot-only tracking cannot carry an account root baseline".into(),
                ));
            }
            if baseline.last_block > coverage.number
                || checkpoint
                    .last_gate_block
                    .is_some_and(|last_gate| baseline.last_block > last_gate)
            {
                return Err(invalid(
                    "root-gate baseline lies beyond the committed gate window".into(),
                ));
            }
        }
        Ok(())
    }

    /// Track `address` under `policy` for the per-block root gate (Phase-8 step 4).
    ///
    /// Tracking is strictly opt-in: a runtime with no tracked accounts runs the
    /// gate as a no-op. Registering an account clears any baseline it held (a
    /// policy change re-adopts on the next probe rather than diffing against a
    /// baseline captured under the old policy). Each [`RootGateCadence`]
    /// firing, the gate
    /// probes tracked [`WholeAccount`](TrackingPolicy::WholeAccount) and
    /// [`Scalars`](TrackingPolicy::Scalars) accounts' roots/fields via the
    /// account-proof seam and, on a move no decoder covered, emits a
    /// [`ReactiveReport::CoverageGap`] and schedules a
    /// [`ResyncReason::RootMoved`] repair. [`Slots`](TrackingPolicy::Slots)
    /// accounts are never root-gated (spec Decision 3).
    pub fn track_account(&mut self, address: Address, policy: TrackingPolicy) {
        self.tracking.insert(address, policy);
        self.tracked_roots.remove(&address);
    }

    /// Stop tracking `address`, dropping its policy and any adopted baseline.
    ///
    /// Returns `true` if the account was tracked.
    pub fn untrack_account(&mut self, address: Address) -> bool {
        self.tracked_roots.remove(&address);
        self.tracking.remove(&address).is_some()
    }

    /// Set how often the root gate probes tracked accounts (default:
    /// [`RootGateCadence::default`] — every 16 canonical blocks; see the
    /// [`RootGateCadence`] docs for why skipping blocks loses no detection).
    ///
    /// Reconfiguring resets the gate's window bookkeeping (the touched-address
    /// accumulator and the last-fired block), so a stale window never leaks
    /// into the new cadence: the next canonical block fires the gate.
    pub fn set_root_gate_cadence(&mut self, cadence: RootGateCadence) {
        self.root_gate_cadence = cadence;
        self.last_gate_block = None;
        self.touched_since_gate.clear();
    }

    /// The configured [`RootGateCadence`].
    pub fn root_gate_cadence(&self) -> RootGateCadence {
        self.root_gate_cadence
    }

    /// Enable freshness stamping of canonical event-derived writes (opt-in).
    ///
    /// Installs a [`FreshnessRegistry`] the runtime owns; while it is present,
    /// applying a canonical handler storage-slot effect for a block `N` stamps the
    /// touched `(address, slot)` as
    /// [`Validity::ValidThrough`](crate::freshness::Validity::ValidThrough)`(N)`.
    /// The slot is therefore not volatile *at* `N` (event-maintained, no need to
    /// re-verify) but ages to volatile once the clock passes `N`.
    ///
    /// Idempotent: if a registry is already installed it is left untouched, so an
    /// existing registry (and any stamps it holds) is never clobbered.
    pub fn enable_freshness_stamping(&mut self) {
        if self.freshness.is_none() {
            self.freshness = Some(FreshnessRegistry::new());
        }
    }

    /// Borrow the runtime's freshness registry, if stamping was enabled.
    ///
    /// Returns `None` unless
    /// [`enable_freshness_stamping`](Self::enable_freshness_stamping) was called.
    pub fn freshness(&self) -> Option<&FreshnessRegistry> {
        self.freshness.as_ref()
    }

    /// Mutably borrow the runtime's freshness registry, if stamping was enabled.
    ///
    /// Returns `None` unless
    /// [`enable_freshness_stamping`](Self::enable_freshness_stamping) was called.
    pub fn freshness_mut(&mut self) -> Option<&mut FreshnessRegistry> {
        self.freshness.as_mut()
    }

    /// Return the current queryable [`CacheHealth`] of the runtime.
    pub fn health(&self) -> CacheHealth {
        self.health
    }

    /// Return a point-in-time snapshot of the runtime's observability counters.
    pub fn metrics(&self) -> CacheMetricsSnapshot {
        self.metrics.snapshot()
    }

    /// Complete the caller-driven self-heal by returning health to
    /// [`CacheHealth::Healthy`].
    ///
    /// A trust-loss event (a reorg deeper than the journal, or a detected missed
    /// block range) escalates health toward [`CacheHealth::Unhealthy`] as a
    /// "stop until rebuilt" signal that the caller must act on. Once the caller
    /// has resynced or rebuilt the affected state, it invokes this to clear the
    /// signal. It does not emit a [`ReactiveReport::Health`] report, since it is
    /// called outside an ingest cycle.
    pub fn reset_health(&mut self) {
        self.health = CacheHealth::Healthy;
    }

    /// Escalate health one rung up the trust-loss ladder for a trust-loss event
    /// observed at `block`, returning a [`ReactiveReport::Health`] report when the
    /// state actually changes.
    ///
    /// The ladder is:
    /// - [`Healthy`](CacheHealth::Healthy) -> [`Degraded`](CacheHealth::Degraded)
    /// - [`Degraded`](CacheHealth::Degraded) -> [`Unhealthy`](CacheHealth::Unhealthy)
    /// - [`Unhealthy`](CacheHealth::Unhealthy) -> no change (`None`)
    ///
    /// A first event degrades; a second escalates to the terminal
    /// [`Unhealthy`](CacheHealth::Unhealthy) stop signal. This is shared by both
    /// trust-loss paths (deep reorg beyond the journal and missed-range
    /// detection) so mixed event types climb the same ladder.
    fn escalate_trust(&mut self, block: u64) -> Option<Arc<ReactiveReport<N>>> {
        let to = match self.health {
            CacheHealth::Healthy => CacheHealth::Degraded { since_block: block },
            CacheHealth::Degraded { .. } => CacheHealth::Unhealthy { since_block: block },
            CacheHealth::Unhealthy { .. } => return None,
        };
        self.transition_health(to, Some(block))
    }

    /// Transition health to `to`, returning a [`ReactiveReport::Health`] report
    /// when the state actually changes.
    ///
    /// The returned report must be threaded into the ingest cycle's dispatched
    /// reports so it reaches hooks and appears in
    /// [`ReactiveBatchReport::reports`]. Returns `None` when `to` equals the
    /// current state (no transition, no report).
    fn transition_health(
        &mut self,
        to: CacheHealth,
        block: Option<u64>,
    ) -> Option<Arc<ReactiveReport<N>>> {
        if to == self.health {
            return None;
        }
        let from = self.health;
        self.health = to;
        Some(Arc::new(ReactiveReport::Health(HealthReport {
            from,
            to,
            block,
            _network: PhantomData,
        })))
    }

    /// Register a handler.
    ///
    /// # Errors
    ///
    /// Returns [`RegisterError::DuplicateHandler`] when the id is already
    /// registered.
    pub fn register_handler(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
    ) -> Result<(), RegisterError> {
        self.registry.register_handler(handler)
    }

    /// Remove one handler from the runtime registry without resetting runtime state.
    ///
    /// This delegates to [`ReactiveRegistry::unregister_handler`] only. It does
    /// not clear the reorg journal, health, metrics, hooks, pending resyncs,
    /// tracking policy, freshness registry, or root-gate baselines, and it does
    /// not purge [`EvmCache`] state. Callers that want cache eviction must issue
    /// explicit `StateUpdate::purge` updates or use cache purge APIs separately.
    pub fn unregister_handler(&mut self, id: &HandlerId) -> Option<Arc<dyn ReactiveHandler<N>>> {
        self.registry.unregister_handler(id)
    }

    /// Return true when the runtime has a registered handler with `id`.
    pub fn contains_handler(&self, id: &HandlerId) -> bool {
        self.registry.contains_handler(id)
    }

    /// Ids of all registered handlers, in registration (= routing) order.
    pub fn handler_ids(&self) -> Vec<HandlerId> {
        self.registry.handler_ids()
    }

    /// Borrow the interests owned by one registered handler.
    pub fn handler_interests(&self, id: &HandlerId) -> Option<&[ReactiveInterest<N>]> {
        self.registry.handler_interests(id)
    }

    /// The most recently journaled canonical block, if any.
    ///
    /// This is the runtime's current chain position: the canonical block most
    /// recently recorded by ingestion. Reorged blocks are dropped from the
    /// journal during recovery, so a rolled-back head does not linger here.
    /// [`ReactiveEngine::register_handler`] uses it as the default backfill
    /// anchor for handlers registered mid-lifecycle. An ordered barrier may
    /// advance this coverage position across an empty event range. `None` until
    /// the first canonical input or barrier is accepted.
    pub fn last_canonical_block(&self) -> Option<BlockRef> {
        self.coverage_head
    }

    /// Adopt an exact RPC snapshot block as this runtime's canonical starting
    /// position without applying effects or dispatching reports.
    ///
    /// Handlers, hooks, tracking policy, and freshness configuration may be
    /// installed before adoption, but no chain input, finality, resync,
    /// root-gate observation, or health transition may have occurred. An exact
    /// repeat is idempotent; a different repeat and any active runtime fail
    /// closed. Prefer [`ReactiveEngine::adopt_canonical_baseline`] when a cache
    /// and subscriber are available so chain identity and the cache's exact
    /// hash pin are validated too.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveBaselineError::ActiveRuntime`] after any runtime
    /// activity, or [`ReactiveBaselineError::ConflictingBaseline`] when a
    /// different baseline has already been adopted.
    pub fn adopt_canonical_baseline(
        &mut self,
        baseline: BlockRef,
    ) -> Result<(), ReactiveBaselineError> {
        self.validate_canonical_baseline_adoption(baseline)?;
        if self.adopted_baseline_only().is_some() {
            return Ok(());
        }

        self.coverage_head = Some(baseline);
        if self.config.journal_depth > 0 {
            self.journal.push_back(BlockJournal {
                block: baseline,
                inputs: Vec::new(),
                applied: Vec::new(),
                handler_ids: Vec::new(),
                resynced: Vec::new(),
                rollback_diffs: Vec::new(),
            });
        }
        Ok(())
    }

    fn validate_canonical_baseline_adoption(
        &self,
        baseline: BlockRef,
    ) -> Result<(), ReactiveBaselineError> {
        if let Some(existing) = self.adopted_baseline_only() {
            return if existing == baseline {
                Ok(())
            } else {
                Err(ReactiveBaselineError::ConflictingBaseline {
                    existing_number: existing.number,
                    existing_hash: existing.hash,
                    requested_number: baseline.number,
                    requested_hash: baseline.hash,
                })
            };
        }
        if !self.is_pristine_for_checkpoint_restore() {
            return Err(ReactiveBaselineError::ActiveRuntime);
        }
        Ok(())
    }

    /// Most recent safe head explicitly reported by the event source.
    pub const fn safe_head(&self) -> Option<&BlockRef> {
        self.safe_head.as_ref()
    }

    /// Most recent finalized head explicitly reported by the event source.
    pub const fn finalized_head(&self) -> Option<&BlockRef> {
        self.finalized_head.as_ref()
    }

    /// Return whether the retained reorg journal still contains an applied
    /// record for `handler_id`.
    ///
    /// The record is retained even when the handler emitted only resync work,
    /// so an owner can keep an explicit cache-eviction fence active for exactly
    /// as long as a later rollback could restore effects from that handler
    /// generation. This query is bounded by [`ReactiveConfig::journal_depth`].
    pub fn has_journaled_handler_effects(&self, handler_id: &HandlerId) -> bool {
        self.journal
            .iter()
            .any(|entry| entry.handler_ids.contains(handler_id))
    }

    /// Return the distinct handler generations represented in the retained
    /// reorg journal.
    ///
    /// This scans the bounded journal once, allowing a lifecycle owner to age a
    /// large set of cache-eviction fences without rescanning the journal for
    /// every handler.
    pub fn journaled_handler_ids(&self) -> HashSet<HandlerId> {
        self.journal
            .iter()
            .flat_map(|entry| entry.handler_ids.iter().cloned())
            .collect()
    }

    /// Queued resync requests: surfaced by handlers but not yet executed by an
    /// [`ingest_batch_with_resync`](Self::ingest_batch_with_resync) pass.
    ///
    /// Callers driving resync execution themselves (plain
    /// [`ingest_batch`](Self::ingest_batch) loops) can read the ledger here;
    /// reorg recovery cancels entries whose pinned blocks were dropped, and
    /// [`cancel_pending_resync`](Self::cancel_pending_resync) drops exact
    /// generation-owned work, while
    /// [`cancel_pending_resyncs`](Self::cancel_pending_resyncs) drops entries
    /// for exclusively torn-down accounts.
    pub fn pending_resyncs(&self) -> &[ResyncRequest] {
        &self.pending_resyncs
    }

    /// Cancel every queued request with the exact logical `id`.
    ///
    /// Unlike [`cancel_pending_resyncs`](Self::cancel_pending_resyncs), this
    /// removes whole requests and never touches other work merely because it
    /// targets the same account. It is therefore the safe primitive for
    /// generation-scoped owner teardown when the caller maintains an
    /// owner-to-[`ResyncId`] index. Requests already returned to the caller in
    /// an earlier batch report cannot be recalled.
    pub fn cancel_pending_resync(&mut self, id: &ResyncId) -> Vec<ResyncRequest> {
        self.cancel_pending_resyncs_by_id(std::slice::from_ref(id))
    }

    /// Cancel queued requests whose logical ids occur in `ids` in one queue pass.
    ///
    /// Duplicate and unknown ids are harmless. Cancelled requests retain their
    /// pending-queue order, independent of caller id order. This is the batch
    /// teardown primitive for owners that can have many pending repairs; it
    /// avoids rescanning the complete pending queue once per owned id.
    pub fn cancel_pending_resyncs_by_id(&mut self, ids: &[ResyncId]) -> Vec<ResyncRequest> {
        if ids.is_empty() {
            return Vec::new();
        }
        let ids: HashSet<&ResyncId> = ids.iter().collect();
        let mut cancelled = Vec::new();
        self.pending_resyncs.retain(|request| {
            if ids.contains(&request.id) {
                cancelled.push(request.clone());
                false
            } else {
                true
            }
        });
        cancelled
    }

    /// Cancel queued resync work that targets `address`, returning the
    /// cancelled portions.
    ///
    /// Every pending [`ResyncRequest`] target referencing `address` is removed;
    /// a request reduced to zero targets is dropped entirely, while
    /// mixed-target requests keep their other accounts queued. Each returned
    /// request mirrors the original id/reason/block/priority and carries only
    /// the targets that were cancelled.
    ///
    /// This is appropriate only when the caller owns the complete account. For
    /// a pool sharing a vault or emitter with other owners, cancel its exact
    /// request IDs through
    /// [`cancel_pending_resync`](Self::cancel_pending_resync) instead. It cannot
    /// recall requests already returned to the caller in earlier batch reports.
    pub fn cancel_pending_resyncs(&mut self, address: Address) -> Vec<ResyncRequest> {
        let mut cancelled = Vec::new();
        self.pending_resyncs.retain_mut(|request| {
            let (matching, remaining): (Vec<_>, Vec<_>) = request
                .targets
                .drain(..)
                .partition(|target| resync_target_address(target) == address);
            request.targets = remaining;
            if !matching.is_empty() {
                cancelled.push(ResyncRequest {
                    id: request.id.clone(),
                    reason: request.reason.clone(),
                    block: request.block.clone(),
                    targets: matching,
                    priority: request.priority,
                });
            }
            !request.targets.is_empty()
        });
        cancelled
    }

    /// Register a hook.
    ///
    /// # Errors
    ///
    /// This implementation is currently infallible; the `Result` preserves the
    /// registration contract for future hook validation.
    pub fn register_hook(&mut self, hook: Arc<dyn ReactiveHook<N>>) -> Result<(), RegisterError> {
        self.hooks.push(hook);
        Ok(())
    }

    /// Return all registered interests in handler registration order.
    pub fn interests(&self) -> Vec<ReactiveInterest<N>> {
        self.registry.interests()
    }

    /// Ingest a batch, apply valid direct state effects, and dispatch reports.
    ///
    /// The commit is atomic on `Err`: cache state and canonical runtime state are
    /// restored before the error returns, and hooks see no reports. Monotonic
    /// observability counters still retain rejected-attempt signals.
    /// The current rollback guard snapshots complete mutable cache state once per
    /// batch, so callers should preserve transport batching rather than splitting
    /// one delivery into many one-record calls.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveError`] when records or controls are invalid, canonical
    /// continuity cannot be proven, a handler rejects input, or an effect cannot
    /// be applied. Cache and canonical runtime state are restored before return.
    pub fn ingest_batch(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveError> {
        let preconfirmation = batch_preconfirmation(&batch)?;
        if let Some(flashblock) = preconfirmation.as_ref() {
            self.prepare_preconfirmed_branch(cache, flashblock)?;
        } else {
            self.discard_preconfirmed_branch(cache);
        }
        let cache_state = EvmCacheStateSnapshot::capture(cache);
        let runtime_state = self.checkpoint_state();
        let batch_report = match self.ingest_batch_direct(cache, batch) {
            Ok(report) => report,
            Err(error) => {
                cache_state.restore(cache);
                self.restore_transaction_state(runtime_state);
                return Err(error);
            }
        };
        if let Some(flashblock) = preconfirmation {
            self.restore_transaction_state(runtime_state);
            if let Some(branch) = self.preconfirmed_branch.as_mut() {
                branch.flashblock = flashblock;
            }
        }
        self.dispatch_reports(&batch_report.reports);
        let _ = &self.config;
        Ok(batch_report)
    }

    /// Ingest a batch, then execute surfaced storage resync requests.
    ///
    /// This entrypoint preserves [`ingest_batch`](Self::ingest_batch) behavior for
    /// direct handler effects, then runs a synchronous resync phase over the
    /// collected [`ResyncRequest`]s. Storage targets are fetched through
    /// [`EvmCache::storage_batch_fetcher`] grouped by [`ResyncBlock`], successful
    /// values are applied as [`StateUpdate::slot`] updates through
    /// [`EvmCache::apply_updates`], and unsupported or failed targets are reported
    /// in [`ResyncReport::failed`]. It does not start subscribers, background
    /// workers, or network transport.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveError`] for the same validation, continuity, handler,
    /// or direct-effect failures as [`ingest_batch`](Self::ingest_batch). Failed
    /// resync targets are reported in the successful batch report instead.
    pub fn ingest_batch_with_resync(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveError> {
        let preconfirmation = batch_preconfirmation(&batch)?;
        if let Some(flashblock) = preconfirmation.as_ref() {
            self.prepare_preconfirmed_branch(cache, flashblock)?;
        } else {
            self.discard_preconfirmed_branch(cache);
        }
        let cache_state = EvmCacheStateSnapshot::capture(cache);
        let runtime_state = self.checkpoint_state();
        let batch_report = match self.ingest_batch_with_resync_direct(cache, batch) {
            Ok(report) => report,
            Err(error) => {
                cache_state.restore(cache);
                self.restore_transaction_state(runtime_state);
                return Err(error);
            }
        };

        if let Some(flashblock) = preconfirmation {
            self.restore_transaction_state(runtime_state);
            if let Some(branch) = self.preconfirmed_branch.as_mut() {
                branch.flashblock = flashblock;
            }
        }

        self.dispatch_reports(&batch_report.reports);
        let _ = &self.config;
        Ok(batch_report)
    }

    /// Active speculative Flashblock snapshot, when the cache currently
    /// includes pre-confirmed effects.
    pub fn active_preconfirmation(&self) -> Option<&FlashblockRef> {
        self.preconfirmed_branch
            .as_ref()
            .map(|branch| &branch.flashblock)
    }

    /// Restore the cache to its canonical state and discard any speculative
    /// Flashblock effects.
    pub fn discard_preconfirmation(&mut self, cache: &mut EvmCache) {
        self.discard_preconfirmed_branch(cache);
    }

    fn discard_preconfirmed_branch(&mut self, cache: &mut EvmCache) {
        if let Some(branch) = self.preconfirmed_branch.take() {
            branch.canonical_cache.restore(cache);
        }
    }

    fn prepare_preconfirmed_branch(
        &mut self,
        cache: &mut EvmCache,
        incoming: &FlashblockRef,
    ) -> Result<(), ReactiveError> {
        if let Some(active) = self.preconfirmed_branch.as_ref()
            && active.flashblock.same_payload(incoming)
        {
            if let (Some(active_index), Some(incoming_index)) =
                (active.flashblock.index, incoming.index)
                && incoming_index < active_index
            {
                return Err(ReactiveError::InvalidInputRecord {
                    message: format!(
                        "Flashblock index regressed from {active_index} to {incoming_index}"
                    ),
                });
            }
            if active.flashblock.index == incoming.index
                && active.flashblock.block_hash != incoming.block_hash
            {
                return Err(ReactiveError::InvalidInputRecord {
                    message:
                        "same Flashblock payload/index carried conflicting partial block hashes"
                            .into(),
                });
            }
            return Ok(());
        }

        self.discard_preconfirmed_branch(cache);
        self.preconfirmed_branch = Some(PreconfirmedBranch {
            flashblock: incoming.clone(),
            canonical_cache: EvmCacheStateSnapshot::capture(cache),
        });
        Ok(())
    }

    fn ingest_batch_with_resync_direct(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveError> {
        let mut batch_report = self.ingest_batch_direct(cache, batch)?;
        if !batch_report.resyncs.is_empty() {
            let resync_report = execute_resync_requests(cache, &batch_report.resyncs);
            // Count unique logical requests: several handlers may emit the same
            // ResyncId in one batch, and duplicates fan out per-origin in the
            // report but are one unit of resync work for the metric.
            let unique_requests = resync_report
                .requested
                .iter()
                .map(|request| &request.id)
                .collect::<HashSet<_>>()
                .len();
            self.metrics
                .resync_requests
                .fetch_add(unique_requests as u64, Ordering::Relaxed);
            self.metrics
                .resync_failures
                .fetch_add(resync_report.failed.len() as u64, Ordering::Relaxed);
            self.remove_pending_resyncs(batch_report.resyncs.iter().map(|request| &request.id));
            self.record_journal_resync(&resync_report);
            batch_report
                .reports
                .push(Arc::new(ReactiveReport::Resynced(resync_report)));
        }
        Ok(batch_report)
    }

    fn ingest_batch_direct(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveError> {
        let (records, chain_controls, batch_chain_id) = batch.into_runtime_parts();
        if let Some(chain_id) = batch_chain_id
            && chain_id != cache.chain_id()
        {
            return Err(ReactiveError::InvalidInputRecord {
                message: format!(
                    "batch chain id {chain_id} does not match cache chain id {}",
                    cache.chain_id()
                ),
            });
        }
        if !chain_controls.is_empty() && batch_chain_id.is_none() {
            return Err(ReactiveError::InvalidChainControl {
                message: "chain-control batches require an authoritative batch chain id".into(),
            });
        }
        for (record, _, _) in &records {
            record.validated_identity()?;
            if let Some(chain_id) = record.context.chain_id
                && chain_id != cache.chain_id()
            {
                return Err(ReactiveError::InvalidInputRecord {
                    message: format!(
                        "input chain id {chain_id} does not match cache chain id {}",
                        cache.chain_id()
                    ),
                });
            }
        }
        let records = sort_scoped_records(dedupe_scoped_records(records)?);

        let mut batch_report = ReactiveBatchReport::default();
        let mut reports_to_dispatch = Vec::new();
        let control_split = validate_control_phase_order(&chain_controls)?;
        let (pre_record_controls, post_record_controls) = chain_controls.split_at(control_split);
        let pre_record_state =
            self.validate_ingest_sequence(pre_record_controls, post_record_controls, &records)?;
        self.validate_owner_catchup_against_journal(&pre_record_state, &records)?;
        let mut batch_dropped = BatchDroppedCanonical::default();
        for control in pre_record_controls {
            if let ChainControl::Reorg {
                common_ancestor,
                old_tip,
                ..
            } = control
            {
                batch_dropped.record_explicit(common_ancestor, old_tip);
                let drained = self
                    .journal
                    .iter()
                    .filter(|entry| entry.block.number > common_ancestor.number)
                    .map(|entry| entry.block)
                    .collect::<Vec<_>>();
                batch_dropped.record_drained(&drained);
            }
        }
        let certified_progress_through = post_record_controls
            .iter()
            .filter_map(canonical_coverage_control_block)
            .map(|block| block.number)
            .max();
        for control in pre_record_controls.iter().cloned() {
            self.apply_chain_control(cache, control, &mut batch_report, &mut reports_to_dispatch);
        }
        // Phase-8 step 4: accumulate the addresses a decoder actually wrote this
        // batch (union of applied `StateDiff` addresses) and the batch's canonical
        // block number, so the per-block root gate can run once after the record
        // loop with the full touched set.
        let mut touched_addrs: HashSet<Address> = HashSet::new();
        let mut canonical_batch_block: Option<u64> = None;

        for (record, audience, delivery_scope) in records {
            let raw_canonical_block = canonical_record_block(&record).copied();
            let canonical_block = raw_canonical_block.map(|block| {
                pre_record_state
                    .resolved_canonical_blocks
                    .get(&(block.number, block.hash))
                    .copied()
                    .unwrap_or(block)
            });
            let input_ref = record.input_ref();
            reports_to_dispatch.push(Arc::new(ReactiveReport::Input(InputReport {
                input_ref,
                context: record.context.clone(),
                provider: record.provider.clone(),
                _network: PhantomData,
            })));

            let recovered_reorg = if delivery_scope.advances_canonical_state() {
                if let Some(block) = canonical_block.as_ref() {
                    let gap_is_certified = delivery_scope == DeliveryScope::CanonicalProgress
                        && certified_progress_through
                            .is_some_and(|through| block.number <= through);
                    let parentless_replacement_is_proven = raw_canonical_block.is_some_and(|raw| {
                        raw.parent_hash.is_none()
                            && batch_dropped.covers_implicit_number(raw.number)
                    });
                    self.recover_for_canonical_input(
                        cache,
                        block,
                        gap_is_certified,
                        parentless_replacement_is_proven,
                        &mut reports_to_dispatch,
                    )
                } else {
                    None
                }
            } else {
                None
            };
            let recovered_reorg_for_input = recovered_reorg.is_some();
            if let Some(reorg_report) = recovered_reorg {
                self.metrics
                    .reorgs_recovered
                    .fetch_add(1, Ordering::Relaxed);
                remove_canceled_resyncs_from_batch(
                    &mut batch_report.resyncs,
                    &reorg_report.canceled_resyncs,
                );
                reports_to_dispatch.push(Arc::new(ReactiveReport::Reorg(reorg_report)));
            }

            // Removed/reorged records are lifecycle signals, never handler
            // data. Canonical scopes may roll back state; owner-only catch-up
            // scopes deliberately cannot, but both must suppress ordinary
            // decoding even when the referenced block is unknown, aged out of
            // the journal, or has already been removed once.
            if reorg_signal_block(&record).is_some() {
                if delivery_scope.advances_canonical_state()
                    && let Some(reorg_report) = self.recover_for_reorged_input(
                        cache,
                        &record,
                        &mut batch_dropped,
                        &mut reports_to_dispatch,
                    )
                {
                    self.metrics
                        .reorgs_recovered
                        .fetch_add(1, Ordering::Relaxed);
                    remove_canceled_resyncs_from_batch(
                        &mut batch_report.resyncs,
                        &reorg_report.canceled_resyncs,
                    );
                    reports_to_dispatch.push(Arc::new(ReactiveReport::Reorg(reorg_report)));
                }
                continue;
            }

            // Preflight validates owner history against the journal state at
            // batch entry. A canonical record earlier in this same transaction
            // may legitimately replace and drain that block, so close the
            // resulting TOCTOU window immediately before any owner handler can
            // mutate the cache. The outer transaction guard restores every
            // earlier record in the batch on failure.
            if delivery_scope == DeliveryScope::OwnerCatchup {
                self.validate_owner_catchup_record_against_current_journal(&record)?;
            }

            if delivery_scope.advances_canonical_state()
                && let Some(block) = canonical_block.as_ref()
            {
                // Phase-8 step 4: remember the batch's canonical block (the last
                // canonical record wins) so the root gate probes at that height.
                canonical_batch_block = Some(block.number);
                self.record_journal_input(block, input_ref);
            }

            // Keep every lazy provider read pinned to the exact event block
            // before handlers run. A full header installs the complete EVM env;
            // compact log-only progress installs NUMBER/timestamp and clears
            // unknown header-only fields. A later record for the same retained
            // canonical block can preserve an already-installed full env.
            if delivery_scope.advances_canonical_state()
                && let Some(block) = canonical_block.as_ref()
            {
                match advance_block_for_canonical_record(cache, &record) {
                    Some(Ok(())) => {
                        cache.advance_compact_block(block.number, block.hash, block.timestamp, true)
                    }
                    Some(Err(err)) => {
                        cache.advance_compact_block(
                            block.number,
                            block.hash,
                            block.timestamp,
                            false,
                        );
                        reports_to_dispatch.push(Arc::new(ReactiveReport::Error(
                            ReactiveErrorReport {
                                input_ref: Some(input_ref),
                                message: err.to_string(),
                                _network: PhantomData,
                            },
                        )));
                    }
                    None => cache.advance_compact_block(
                        block.number,
                        block.hash,
                        block.timestamp,
                        !recovered_reorg_for_input,
                    ),
                }
            }

            let executions = self.execute_handlers(cache, &record, input_ref, &audience)?;
            if executions.is_empty() {
                continue;
            }

            reports_to_dispatch.push(Arc::new(ReactiveReport::Decoded(DecodedReport {
                input_ref,
                handler_ids: executions
                    .iter()
                    .map(|execution| execution.handler_id.clone())
                    .collect(),
                _network: PhantomData,
            })));

            detect_conflicts(input_ref, &executions)?;

            // Phase-8 step 3: canonical block number for freshness stamping.
            // Copied out as a plain `u64` (dropping the borrow of `record`) so it
            // can be used while `self.freshness_mut()` mutably borrows `self`
            // inside the execution loop. `None` for pending/removed/reorged
            // records — those never stamp canonical freshness.
            let canonical_block_number = delivery_scope
                .advances_canonical_state()
                .then_some(canonical_block)
                .flatten()
                .map(|block| block.number);

            for execution in executions {
                let diff = if execution.state_updates.is_empty() {
                    StateDiff::default()
                } else {
                    cache.apply_updates(&execution.state_updates)
                };

                batch_report
                    .resyncs
                    .extend(execution.resyncs.iter().cloned());
                self.pending_resyncs
                    .extend(execution.resyncs.iter().cloned());
                batch_report
                    .speculative
                    .extend(execution.speculative.iter().cloned());

                let applied = AppliedReport {
                    input_ref,
                    handler_id: execution.handler_id,
                    quality: execution.quality,
                    tags: execution.tags,
                    diff,
                    state_updates: execution.state_updates,
                    invalidations: execution.invalidations,
                    resyncs: execution.resyncs,
                    speculative: execution.speculative,
                    hook_signals: execution.hook_signals,
                    _network: PhantomData,
                };
                // Phase-8 step 3 (opt-in): stamp every touched `(address, slot)`
                // from this canonical handler write as `ValidThrough(N)`, so an
                // event-maintained slot stops being re-verified until the clock
                // passes its write block. Read the changed slots straight off
                // `applied.diff` (which borrows the local, not `self`) and stamp
                // via `self.freshness`, done before `applied` is moved into the
                // journal/batch below. Only genuinely-changed slots appear here,
                // since a no-op re-write records no `SlotChange`.
                if let (Some(number), Some(registry)) =
                    (canonical_block_number, self.freshness.as_mut())
                {
                    for change in &applied.diff.slots {
                        registry.valid_through_slot(change.address, change.slot, number);
                    }
                }

                // Phase-8 step 4: record every address this decoder actually wrote
                // (or attempted to write) so the root gate can tell a
                // decoder-covered root move from an uncovered coverage gap. Fold in
                // the full `StateDiff` address footprint — real changes
                // (`slots`/`accounts`/`purged`) and cold-skipped attempts alike, so
                // a decoder that tried to write a cold slot still counts as
                // covering the account.
                if delivery_scope.advances_canonical_state() {
                    collect_diff_addresses(&applied.diff, &mut touched_addrs);
                }

                let report = Arc::new(ReactiveReport::Applied(applied.clone()));
                reports_to_dispatch.push(report);
                if let Some(block) = canonical_block.as_ref() {
                    if delivery_scope.advances_canonical_state() {
                        self.record_journal_applied(block, applied.clone());
                    } else {
                        self.record_journal_applied_if_present(block, applied.clone());
                    }
                }
                batch_report.applied.push(applied);
            }
        }

        // Coverage/finality controls certify the records that precede them.
        // Applying them here also leaves the live cache pinned to a certified
        // zero-event tail rather than the last block that happened to emit a
        // matching log. Reorg controls were applied before the record loop.
        for control in post_record_controls.iter().cloned() {
            if let Some(block) = canonical_coverage_control_block(&control) {
                canonical_batch_block = Some(
                    canonical_batch_block.map_or(block.number, |current| current.max(block.number)),
                );
            }
            self.apply_chain_control(cache, control, &mut batch_report, &mut reports_to_dispatch);
        }

        // Phase-8 step 4 + §6.2 cadence: accumulate this batch's touched
        // addresses (after all handler effects, so the set is complete), then
        // fire the root gate only on cadence boundaries. The gate diffs
        // against persisted baselines, so skipped blocks lose no detection —
        // but the touched set must be the union since the last firing, or a
        // decoder-covered write in a skipped block would false-positive as a
        // CoverageGap. Fired resyncs surface in `batch_report.resyncs` (so
        // callers see them and `ingest_batch_with_resync` executes them) and
        // coverage reports go into the dispatched reports.
        if self.root_gate_runnable(cache) {
            self.touched_since_gate
                .extend(touched_addrs.iter().copied());
            if self.root_gate_due(canonical_batch_block) {
                let accumulated = std::mem::take(&mut self.touched_since_gate);
                self.run_root_gate(
                    cache,
                    canonical_batch_block,
                    &accumulated,
                    &mut batch_report.resyncs,
                    &mut reports_to_dispatch,
                );
                self.last_gate_block = canonical_batch_block;
            }
        } else {
            // A gate that cannot run (disabled, nothing root-gated, or no
            // proof fetcher) must not grow the accumulator unboundedly.
            // Dropping it is safe: without a runnable gate no baselines exist
            // (a fetcher cannot be uninstalled, and untracking drops the
            // baseline), so there is nothing a lost touched set could falsely
            // gap against later.
            self.touched_since_gate.clear();
        }

        batch_report.reports = reports_to_dispatch;
        Ok(batch_report)
    }

    /// Prove that every owner-only historical effect can be attached to an
    /// compatible retained canonical journal entry before any chain control or
    /// handler mutation is applied. Number/hash are exact. Parent/timestamp are
    /// optional enrichment, but two present values must agree; this matches the
    /// [`BlockRef`] compatibility rule used for cross-source deduplication.
    ///
    /// Owner catch-up deliberately does not advance canonical coverage. Its
    /// effects are appended to the already-existing journal entry so a later
    /// reorg can roll them back with the rest of that block. Accepting a block
    /// outside the journal would make the cache mutation irreversible. A reorg
    /// control in the same batch also invalidates entries above its ancestor,
    /// so those entries are rejected even though they still exist at this
    /// preflight point.
    fn validate_owner_catchup_against_journal(
        &self,
        control_state: &ChainControlState,
        records: &[(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)],
    ) -> Result<(), ReactiveError> {
        for (record, _, delivery_scope) in records {
            if *delivery_scope != DeliveryScope::OwnerCatchup {
                continue;
            }
            // Removed/reorged inputs are lifecycle signals only. Owner catch-up
            // cannot make them canonical and the record loop deliberately skips
            // handler execution, so there is no effect that needs attaching to
            // a rollback journal entry.
            if reorg_signal_block(record).is_some() {
                continue;
            }
            let context_block = canonical_record_block(record).ok_or_else(|| {
                ReactiveError::InvalidChainControl {
                    message: "owner catch-up input has no canonical block identity".into(),
                }
            })?;
            let block = resolve_record_block_payload_metadata(record, *context_block)?;
            let invalidated_by_control = control_state
                .journal_invalidated_from
                .is_some_and(|from| block.number >= from);
            let rollbackable = !invalidated_by_control
                && self.journal.iter().any(|entry| {
                    optional_block_refs_are_compatible(Some(&entry.block), Some(&block))
                });
            if !rollbackable {
                return Err(ReactiveError::OwnerCatchupOutsideJournal {
                    number: block.number,
                    hash: block.hash,
                });
            }
        }
        Ok(())
    }

    fn validate_owner_catchup_record_against_current_journal(
        &self,
        record: &ReactiveInputRecord<N>,
    ) -> Result<(), ReactiveError> {
        let context_block =
            canonical_record_block(record).ok_or_else(|| ReactiveError::InvalidChainControl {
                message: "owner catch-up input has no canonical block identity".into(),
            })?;
        let block = resolve_record_block_payload_metadata(record, *context_block)?;
        if self
            .journal
            .iter()
            .any(|entry| optional_block_refs_are_compatible(Some(&entry.block), Some(&block)))
        {
            return Ok(());
        }
        Err(ReactiveError::OwnerCatchupOutsideJournal {
            number: block.number,
            hash: block.hash,
        })
    }

    /// Whether the root gate could produce any signal at all: some tracked
    /// account is root-gated (`Slots` never is) and a proof fetcher exists.
    /// When this is false the touched accumulator is dropped rather than
    /// grown (see the ingest call site for why that is safe).
    fn root_gate_runnable(&self, cache: &EvmCache) -> bool {
        if matches!(self.root_gate_cadence, RootGateCadence::Disabled) {
            return false;
        }
        let has_gated_targets = self
            .tracking
            .values()
            .any(|policy| !matches!(policy, TrackingPolicy::Slots { .. }));
        has_gated_targets && cache.account_proof_fetcher().is_some()
    }

    /// Whether the root gate is due at this batch's canonical block (§6.2):
    /// the first canonical block ever seen always fires (baseline adoption
    /// must not wait a full window), then at most once every `n` blocks.
    fn root_gate_due(&self, canonical_block: Option<u64>) -> bool {
        let Some(block) = canonical_block else {
            return false;
        };
        match self.root_gate_cadence {
            RootGateCadence::Disabled => false,
            RootGateCadence::EveryNBlocks(n) => match self.last_gate_block {
                None => true,
                Some(last) => block >= last.saturating_add(n.get()),
            },
        }
    }

    /// The `storageHash` root gate (Phase-8 step 4), fired per
    /// [`RootGateCadence`] window (§6.2).
    ///
    /// Runs at the firing batch's canonical block, with `touched` carrying the
    /// union of decoder-touched addresses since the previous firing. For each tracked
    /// [`WholeAccount`](TrackingPolicy::WholeAccount) / [`Scalars`](TrackingPolicy::Scalars)
    /// account, probe the root (and account fields) via the account-proof seam and
    /// apply the spec §4 table:
    ///
    /// - No baseline yet ⇒ **adopt** (no gap, no resync — adoption is not a gap).
    /// - [`WholeAccount`](TrackingPolicy::WholeAccount) root unchanged ⇒ nothing.
    /// - [`WholeAccount`](TrackingPolicy::WholeAccount) root moved, `addr ∈ touched`
    ///   ⇒ a decoder covered it; re-adopt, no gap.
    /// - [`WholeAccount`](TrackingPolicy::WholeAccount) root moved, `addr ∉ touched`
    ///   ⇒ emit [`ReactiveReport::CoverageGap`], count it, schedule a
    ///   [`ResyncReason::RootMoved`] account resync, re-adopt.
    /// - [`Scalars`](TrackingPolicy::Scalars) ⇒ compare balance/nonce/code-hash to
    ///   the baseline (native field changes never move the storage root); on a move
    ///   with `addr ∉ touched`, schedule a [`ResyncReason::RootMoved`] account
    ///   resync for the changed fields and re-adopt.
    ///
    /// No-op when the tracking registry is empty, when the batch has no canonical
    /// block, or when the cache has no account-proof fetcher installed.
    /// [`Slots`](TrackingPolicy::Slots) accounts are never root-gated (spec
    /// Decision 3).
    fn run_root_gate(
        &mut self,
        cache: &EvmCache,
        canonical_block: Option<u64>,
        touched: &HashSet<Address>,
        resyncs: &mut Vec<ResyncRequest>,
        reports: &mut Vec<Arc<ReactiveReport<N>>>,
    ) {
        if self.tracking.is_empty() {
            return;
        }
        let Some(block) = canonical_block else {
            return;
        };
        let Some(fetcher) = cache.account_proof_fetcher().cloned() else {
            return;
        };

        // Collect the root-gated targets (Slots opts out) in a stable order so a
        // single-block sequence of resyncs/reports is deterministic.
        let mut targets: Vec<(Address, bool)> = self
            .tracking
            .iter()
            .filter_map(|(address, policy)| match policy {
                TrackingPolicy::Slots { .. } => None,
                TrackingPolicy::WholeAccount => Some((*address, true)),
                TrackingPolicy::Scalars => Some((*address, false)),
            })
            .collect();
        if targets.is_empty() {
            return;
        }
        targets.sort_by_key(|(address, _)| *address);

        let block_id = BlockId::number(block);
        // ONE seam invocation carries every root-gated target (root-only
        // probes: no storage keys needed). eth_getProof is single-address at
        // the RPC level, so batching here lets the fetcher fan the requests
        // out concurrently instead of paying N sequential round trips.
        let mut probes: HashMap<Address, StorageFetchResult<AccountProof>> = (fetcher)(
            targets
                .iter()
                .map(|&(address, _)| (address, vec![]))
                .collect(),
            block_id,
        )
        .into_iter()
        .collect();
        for (address, whole_account) in targets {
            let Some(Ok(proof)) = probes.remove(&address) else {
                // A failed/omitted probe carries no signal; leave the baseline
                // untouched and try again next block.
                continue;
            };

            let baseline = self.tracked_roots.get(&address).cloned();
            let Some(baseline) = baseline else {
                // First observation: adopt the baseline. Not a coverage gap.
                self.adopt_root(address, block, &proof);
                continue;
            };

            // A stale probe (a batch whose canonical block is not newer than the
            // last one we baselined this account against) carries no forward
            // signal: skip it rather than diff against — or clobber — a newer
            // baseline.
            if block <= baseline.last_block {
                continue;
            }

            if whole_account {
                if proof.storage_hash == baseline.last_root {
                    // Tight steady-state path: unchanged root ⇒ nothing.
                    continue;
                }
                // Root moved.
                if !touched.contains(&address) {
                    // Moved with no covering decoder — the coverage gap.
                    reports.push(Arc::new(ReactiveReport::CoverageGap(CoverageGapReport {
                        address,
                        block,
                        _network: PhantomData,
                    })));
                    self.metrics.coverage_gaps.fetch_add(1, Ordering::Relaxed);
                    resyncs.push(root_moved_account_resync(
                        address,
                        block,
                        AccountFieldMask {
                            balance: true,
                            nonce: true,
                            code: true,
                        },
                    ));
                }
                // Adopt the new root whether or not a decoder covered it.
                self.adopt_root(address, block, &proof);
            } else {
                // Scalars: compare the account fields directly (native changes do
                // not move the storage root).
                let balance_moved = proof.balance != baseline.balance;
                let nonce_moved = proof.nonce != baseline.nonce;
                let code_moved = proof.code_hash != baseline.code_hash;
                if (balance_moved || nonce_moved || code_moved) && !touched.contains(&address) {
                    resyncs.push(root_moved_account_resync(
                        address,
                        block,
                        AccountFieldMask {
                            balance: balance_moved,
                            nonce: nonce_moved,
                            code: code_moved,
                        },
                    ));
                }
                self.adopt_root(address, block, &proof);
            }
        }
    }

    /// Adopt (or re-adopt) `proof` as the baseline for `address` at `block`.
    fn adopt_root(&mut self, address: Address, block: u64, proof: &AccountProof) {
        self.tracked_roots.insert(
            address,
            TrackedRoot {
                last_root: proof.storage_hash,
                last_block: block,
                balance: proof.balance,
                nonce: proof.nonce,
                code_hash: proof.code_hash,
            },
        );
    }

    fn execute_handlers(
        &self,
        cache: &EvmCache,
        record: &ReactiveInputRecord<N>,
        input_ref: InputRef,
        audience: &DeliveryAudience,
    ) -> Result<Vec<HandlerExecution>, ReactiveError> {
        let mut executions = Vec::new();
        let candidates: Vec<_> = match &record.input {
            ReactiveInput::Log(log) => self.registry.log_handler_candidates(log),
            ReactiveInput::BlockHeader(_)
            | ReactiveInput::FullBlock(_)
            | ReactiveInput::PendingTxHash(_)
            | ReactiveInput::PendingTx(_) => self.registry.handlers().collect(),
        };
        for registered in candidates {
            match audience {
                DeliveryAudience::Owners(owners) if !owners.contains(&registered.id) => continue,
                DeliveryAudience::AllExcept(excluded) if excluded.contains(&registered.id) => {
                    continue;
                }
                DeliveryAudience::All
                | DeliveryAudience::Owners(_)
                | DeliveryAudience::AllExcept(_) => {}
            }
            if !registered.matches(&record.input) {
                continue;
            }

            let outcome = registered
                .handler
                .handle(&record.context, &record.input, cache)
                .map_err(|source| ReactiveError::HandlerFailed {
                    handler_id: registered.id.clone(),
                    source,
                })?;

            if let Err(error) =
                validate_effects(input_ref, &record.context, &registered.id, &outcome.effects)
            {
                if matches!(error, ReactiveError::InvalidPendingEffect { .. }) {
                    self.metrics
                        .pending_contamination
                        .fetch_add(1, Ordering::Relaxed);
                }
                return Err(error);
            }
            executions.push(HandlerExecution::from_outcome(
                registered.id.clone(),
                input_ref,
                outcome,
                matches!(
                    record.context.chain_status,
                    ChainStatus::Preconfirmed { .. }
                ),
            ));
        }
        Ok(executions)
    }

    fn dispatch_reports(&self, reports: &[Arc<ReactiveReport<N>>]) {
        for report in reports {
            for hook in &self.hooks {
                hook.on_report(report.clone());
            }
        }
    }

    fn apply_chain_control(
        &mut self,
        cache: &mut EvmCache,
        control: ChainControl,
        batch_report: &mut ReactiveBatchReport<N>,
        reports: &mut Vec<Arc<ReactiveReport<N>>>,
    ) {
        match &control {
            ChainControl::Safe(block) => set_or_enrich_block_ref(&mut self.safe_head, block),
            ChainControl::Finalized(block) => {
                set_or_enrich_block_ref(&mut self.finalized_head, block);
            }
            ChainControl::CanonicalProgress(block)
            | ChainControl::Barrier {
                block: Some(block), ..
            } => {
                let preserve_env = self.coverage_head.as_ref().is_some_and(|current| {
                    optional_block_refs_are_compatible(Some(current), Some(block))
                });
                cache.advance_compact_block(
                    block.number,
                    block.hash,
                    block.timestamp,
                    preserve_env,
                );
                advance_or_enrich_coverage(&mut self.coverage_head, block);
                let enriched = self.journal_entry_mut(block).block;
                advance_or_enrich_coverage(&mut self.coverage_head, &enriched);
                self.trim_journal();
            }
            ChainControl::Barrier { block: None, .. } => {}
            ChainControl::Reorg {
                common_ancestor,
                old_tip,
                ..
            } => {
                cache.invalidate_cached_block_hashes_from(common_ancestor.number.saturating_add(1));
                self.rebase_validation_state_from(common_ancestor.number.saturating_add(1));
                let dropped = if let Some(ancestor_index) = self.journal.iter().rposition(|entry| {
                    entry.block.number == common_ancestor.number
                        && entry.block.hash == common_ancestor.hash
                }) {
                    self.drain_journal_after(ancestor_index)
                } else {
                    // Sparse journals are expected for blocks with no matching
                    // events. If the oldest retained entry is at or below the
                    // ancestor, every effect above it is still present and the
                    // rollback is complete even without an exact anchor.
                    if self
                        .journal
                        .front()
                        .is_none_or(|entry| entry.block.number > common_ancestor.number)
                    {
                        reports.extend(
                            self.warn_under_recovery(common_ancestor.number.saturating_add(1)),
                        );
                    }
                    self.drain_journal_from_number(common_ancestor.number.saturating_add(1))
                };

                let reorg_report = self
                    .recover_dropped_journals(cache, dropped, ReorgReason::Explicit)
                    .unwrap_or_else(|| ReorgReport {
                        dropped: Some(*old_tip),
                        dropped_blocks: Vec::new(),
                        dropped_inputs: Vec::new(),
                        rollback_updates: Vec::new(),
                        rollback_diff: StateDiff::default(),
                        purge_updates: Vec::new(),
                        purge_diff: StateDiff::default(),
                        canceled_resyncs: self
                            .cancel_resyncs_for_dropped_blocks(std::slice::from_ref(old_tip)),
                        reason: ReorgReason::Explicit,
                        _network: PhantomData,
                    });
                remove_canceled_resyncs_from_batch(
                    &mut batch_report.resyncs,
                    &reorg_report.canceled_resyncs,
                );
                self.metrics
                    .reorgs_recovered
                    .fetch_add(1, Ordering::Relaxed);
                reports.push(Arc::new(ReactiveReport::Reorg(reorg_report)));

                if self.safe_head.as_ref().is_some_and(|head| {
                    head.number > common_ancestor.number
                        || (head.number == common_ancestor.number
                            && head.hash != common_ancestor.hash)
                }) {
                    self.safe_head = None;
                }
                if self.finalized_head.as_ref().is_some_and(|head| {
                    head.number > common_ancestor.number
                        || (head.number == common_ancestor.number
                            && head.hash != common_ancestor.hash)
                }) {
                    self.finalized_head = None;
                }
                let mut enriched_ancestor = *common_ancestor;
                if let Some(entry) = self.journal.iter().find(|entry| {
                    entry.block.number == common_ancestor.number
                        && entry.block.hash == common_ancestor.hash
                }) {
                    enrich_block_ref(&mut enriched_ancestor, &entry.block);
                }
                if let Some(current) = self.coverage_head.as_ref()
                    && current.number == common_ancestor.number
                    && current.hash == common_ancestor.hash
                {
                    enrich_block_ref(&mut enriched_ancestor, current);
                }
                self.coverage_head = Some(enriched_ancestor);
                cache.advance_compact_block(
                    enriched_ancestor.number,
                    enriched_ancestor.hash,
                    enriched_ancestor.timestamp,
                    false,
                );
                let enriched_ancestor = self.journal_entry_mut(&enriched_ancestor).block;
                self.coverage_head = Some(enriched_ancestor);
                self.trim_journal();
            }
        }
        reports.push(Arc::new(ReactiveReport::ChainControl(ChainControlReport {
            control,
        })));
    }

    fn validate_ingest_sequence(
        &self,
        pre_record_controls: &[ChainControl],
        post_record_controls: &[ChainControl],
        records: &[(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)],
    ) -> Result<ChainControlState, ReactiveError> {
        let mut controls =
            Vec::with_capacity(pre_record_controls.len() + post_record_controls.len());
        controls.extend_from_slice(pre_record_controls);
        controls.extend_from_slice(post_record_controls);
        let state = CanonicalSequenceState::new(
            self.journal.iter().map(|entry| entry.block).collect(),
            self.coverage_head,
            self.safe_head,
            self.finalized_head,
        );
        let record_metadata = records
            .iter()
            .map(|(record, _, scope)| (record, *scope))
            .collect::<Vec<_>>();
        let validation = validate_canonical_sequence_parts(
            &state,
            &controls,
            &record_metadata,
            CanonicalSequenceValidationPolicy::ObserveIncompleteRollback,
        )
        .map_err(CanonicalSequenceError::into_reactive_error)?;
        let mut resolved_canonical_blocks = HashMap::new();
        for mutation in validation.mutations() {
            if let CanonicalSequenceMutation::Canonical(block) = mutation {
                resolved_canonical_blocks
                    .entry((block.number, block.hash))
                    .and_modify(|known| enrich_block_ref(known, block))
                    .or_insert(*block);
            }
        }
        Ok(ChainControlState {
            journal_invalidated_from: pre_record_controls
                .iter()
                .filter_map(|control| match control {
                    ChainControl::Reorg {
                        common_ancestor, ..
                    } => Some(common_ancestor.number.saturating_add(1)),
                    _ => None,
                })
                .min(),
            resolved_canonical_blocks,
        })
    }

    fn recover_for_canonical_input(
        &mut self,
        cache: &mut EvmCache,
        block: &BlockRef,
        gap_is_certified: bool,
        parentless_replacement_is_proven: bool,
        health_reports: &mut Vec<Arc<ReactiveReport<N>>>,
    ) -> Option<ReorgReport<N>> {
        let latest = self
            .coverage_head
            .or_else(|| self.journal.back().map(|entry| entry.block))?;

        if latest.number == block.number && latest.hash == block.hash {
            return None;
        }

        if self
            .journal
            .iter()
            .any(|entry| entry.block.hash == block.hash && entry.block.number == block.number)
        {
            return None;
        }

        if latest.number.checked_add(1) == Some(block.number)
            && (block.parent_hash == Some(latest.hash)
                || (parentless_replacement_is_proven && block.parent_hash.is_none()))
        {
            return None;
        }

        if latest
            .number
            .checked_add(1)
            .is_some_and(|next| block.number > next)
        {
            // A forward gap: blocks between the journaled head and the arriving
            // block were never observed (e.g. a disconnect). A historical
            // canonical-progress delivery can instead be covered by a
            // compatible post-record progress/barrier certificate proving the
            // sparse interval contained no matching events. Live canonical
            // gaps remain observable and escalate health.
            if !gap_is_certified {
                self.metrics.missed_ranges.fetch_add(1, Ordering::Relaxed);
                health_reports.extend(self.escalate_trust(block.number));
                health_reports.push(Arc::new(ReactiveReport::MissedBlockRange(
                    MissedRangeReport {
                        from: latest.number + 1,
                        to: block.number - 1,
                        block: block.number,
                        _network: PhantomData,
                    },
                )));
            }
            return None;
        }

        let (dropped, authenticated_anchor) = if let Some(parent_hash) = block.parent_hash {
            if let Some(parent_index) = self.journal.iter().rposition(|entry| {
                entry.block.number.checked_add(1) == Some(block.number)
                    && entry.block.hash == parent_hash
            }) {
                let parent = self.journal[parent_index].block;
                cache.invalidate_cached_block_hashes_from(parent.number.saturating_add(1));
                (self.drain_journal_after(parent_index), Some(parent))
            } else {
                // An unknown immediate parent proves exactly N-1 and nothing
                // earlier. Preserve a prefix only when the accepted path is an
                // immediate child of the runtime's exact finalized anchor;
                // otherwise every cached BLOCKHASH may belong to the displaced
                // branch and must be cleared fail-closed.
                let proven_finalized_anchor = self.finalized_head.filter(|finalized| {
                    finalized.number.checked_add(1) == Some(block.number)
                        && parent_hash == finalized.hash
                });
                let invalidated_from = proven_finalized_anchor
                    .map_or(0, |finalized| finalized.number.saturating_add(1));
                cache.invalidate_cached_block_hashes_from(invalidated_from);
                if block.number > 0 {
                    // Even when the parent falls outside the retained journal,
                    // the arriving child authenticates its exact hash. Restore
                    // that one known value after clearing the displaced branch.
                    cache.set_cached_block_hash(block.number.saturating_sub(1), parent_hash);
                }
                health_reports.extend(self.warn_under_recovery(block.number));
                let dropped = if let Some(finalized) = proven_finalized_anchor {
                    self.drain_journal_from_number(finalized.number.saturating_add(1))
                } else {
                    self.drain_journal_from_number(0)
                };
                (dropped, proven_finalized_anchor)
            }
        } else {
            // No parent identity authenticates any prefix of the arriving path.
            cache.invalidate_cached_block_hashes_from(0);
            health_reports.extend(self.warn_under_recovery(block.number));
            (self.drain_journal_from_number(0), None)
        };

        self.rebase_validation_state_from(
            authenticated_anchor.map_or(0, |anchor| anchor.number.saturating_add(1)),
        );
        let report = self
            .recover_dropped_journals(cache, dropped, ReorgReason::ParentMismatch)
            .or_else(|| {
                Some(ReorgReport {
                    dropped: Some(latest),
                    dropped_blocks: Vec::new(),
                    dropped_inputs: Vec::new(),
                    rollback_updates: Vec::new(),
                    rollback_diff: StateDiff::default(),
                    purge_updates: Vec::new(),
                    purge_diff: StateDiff::default(),
                    canceled_resyncs: self
                        .cancel_resyncs_for_dropped_blocks(std::slice::from_ref(&latest)),
                    reason: ReorgReason::ParentMismatch,
                    _network: PhantomData,
                })
            });
        self.coverage_head = authenticated_anchor;
        for head in [&mut self.safe_head, &mut self.finalized_head] {
            if head.is_some_and(|head| {
                authenticated_anchor.is_none_or(|anchor| {
                    head.number > anchor.number
                        || (head.number == anchor.number && head.hash != anchor.hash)
                })
            }) {
                *head = None;
            }
        }
        if let Some(anchor) = authenticated_anchor {
            cache.advance_compact_block(anchor.number, anchor.hash, anchor.timestamp, false);
        }
        report
    }

    fn recover_for_reorged_input(
        &mut self,
        cache: &mut EvmCache,
        record: &ReactiveInputRecord<N>,
        batch_dropped: &mut BatchDroppedCanonical,
        health_reports: &mut Vec<Arc<ReactiveReport<N>>>,
    ) -> Option<ReorgReport<N>> {
        let (incoming_dropped_block, reason) = reorg_signal_block(record)?;
        if batch_dropped.contains(&incoming_dropped_block) {
            // A previous signal in this atomic batch already drained this
            // block/span. Preserve the lifecycle input report, but do not
            // repeat rollback or classify the provider's per-log removals as a
            // deep reorg. Exact hash-pinned repairs still need cancellation.
            let canceled_resyncs = self
                .cancel_resyncs_for_dropped_blocks(std::slice::from_ref(&incoming_dropped_block));
            return (!canceled_resyncs.is_empty()).then(|| ReorgReport {
                dropped: Some(incoming_dropped_block),
                dropped_blocks: vec![incoming_dropped_block],
                dropped_inputs: Vec::new(),
                rollback_updates: Vec::new(),
                rollback_diff: StateDiff::default(),
                purge_updates: Vec::new(),
                purge_diff: StateDiff::default(),
                canceled_resyncs,
                reason,
                _network: PhantomData,
            });
        }
        let exact_index = self.journal.iter().position(|entry| {
            entry.block.number == incoming_dropped_block.number
                && entry.block.hash == incoming_dropped_block.hash
        });
        let mut dropped_block = exact_index
            .map(|index| self.journal[index].block)
            .or_else(|| {
                self.coverage_head.filter(|known| {
                    known.number == incoming_dropped_block.number
                        && known.hash == incoming_dropped_block.hash
                })
            })
            .unwrap_or(incoming_dropped_block);
        enrich_block_ref(&mut dropped_block, &incoming_dropped_block);
        let replacement_is_known = exact_index.is_none()
            && (self.journal.iter().any(|entry| {
                entry.block.number == dropped_block.number && entry.block.hash != dropped_block.hash
            }) || self.coverage_head.is_some_and(|head| {
                head.number == dropped_block.number && head.hash != dropped_block.hash
            }));

        if replacement_is_known {
            // A delayed/duplicate removed log for the displaced hash is
            // idempotent. Draining by number here would destroy the already
            // installed replacement branch at the same height.
            let canceled_resyncs =
                self.cancel_resyncs_for_dropped_blocks(std::slice::from_ref(&dropped_block));
            return (!canceled_resyncs.is_empty()).then(|| ReorgReport {
                dropped: Some(dropped_block),
                dropped_blocks: vec![dropped_block],
                dropped_inputs: Vec::new(),
                rollback_updates: Vec::new(),
                rollback_diff: StateDiff::default(),
                purge_updates: Vec::new(),
                purge_diff: StateDiff::default(),
                canceled_resyncs,
                reason,
                _network: PhantomData,
            });
        }

        let authenticated_anchor = exact_index.and_then(|index| {
            let ancestor_number = dropped_block.number.checked_sub(1)?;
            let retained = self
                .journal
                .iter()
                .take(index)
                .rev()
                .find(|entry| entry.block.number == ancestor_number)
                .map(|entry| entry.block);
            let synthetic_parent = dropped_block.parent_hash.map(|hash| BlockRef {
                number: ancestor_number,
                hash,
                parent_hash: None,
                timestamp: None,
            });
            let finalized_fallback = self
                .finalized_head
                .filter(|head| head.number == ancestor_number);
            let mut anchor = retained.or(synthetic_parent).or(finalized_fallback)?;
            for head in [self.safe_head.as_ref(), self.finalized_head.as_ref()]
                .into_iter()
                .flatten()
            {
                if head.number == anchor.number && head.hash == anchor.hash {
                    enrich_block_ref(&mut anchor, head);
                }
            }
            Some(anchor)
        });

        cache.invalidate_cached_block_hashes_from(dropped_block.number);
        let dropped = if let Some(index) = exact_index {
            self.drain_journal_from(index)
        } else {
            health_reports.extend(self.warn_under_recovery(dropped_block.number));
            self.drain_journal_from_number(dropped_block.number)
        };
        let drained_blocks = dropped.iter().map(|entry| entry.block).collect::<Vec<_>>();
        batch_dropped.record_drained(&drained_blocks);
        batch_dropped.record_identity(&dropped_block);
        self.rebase_validation_state_from(dropped_block.number);

        let recovered_journal = !dropped.is_empty();
        let report = if !recovered_journal {
            let canceled_resyncs =
                self.cancel_resyncs_for_dropped_blocks(std::slice::from_ref(&dropped_block));
            Some(ReorgReport {
                dropped: Some(dropped_block),
                dropped_blocks: Vec::new(),
                dropped_inputs: Vec::new(),
                rollback_updates: Vec::new(),
                rollback_diff: StateDiff::default(),
                purge_updates: Vec::new(),
                purge_diff: StateDiff::default(),
                canceled_resyncs,
                reason,
                _network: PhantomData,
            })
        } else {
            self.recover_dropped_journals(cache, dropped, reason)
        };

        if recovered_journal {
            if let Some(anchor) = authenticated_anchor {
                self.coverage_head = Some(anchor);
            }
            let coverage = self.coverage_head;
            for head in [&mut self.safe_head, &mut self.finalized_head] {
                if head.is_some_and(|head| {
                    coverage.is_none_or(|coverage| {
                        head.number > coverage.number
                            || (head.number == coverage.number && head.hash != coverage.hash)
                    })
                }) {
                    *head = None;
                }
            }
        }

        if recovered_journal
            && report.is_some()
            && let Some(head) = self.coverage_head
        {
            cache.advance_compact_block(head.number, head.hash, head.timestamp, false);
        }
        report
    }

    /// Warn that a reorg references a block no longer resident in the journal, so
    /// recovery is limited to the blocks still journaled — effects from aged-out
    /// blocks are neither rolled back nor purged (the freshness/validation loop is
    /// the backstop). Makes the under-recovery observable instead of silent.
    ///
    /// This is a deep reorg: it increments the `deep_reorgs` counter and escalates
    /// health along the trust-loss ladder via [`escalate_trust`](Self::escalate_trust)
    /// (a first event degrades to [`CacheHealth::Degraded`], a second escalates to
    /// [`CacheHealth::Unhealthy`]). Any resulting [`ReactiveReport::Health`]
    /// transition is returned so the caller can thread it into the ingest cycle's
    /// dispatched reports.
    fn warn_under_recovery(&mut self, reorg_number: u64) -> Option<Arc<ReactiveReport<N>>> {
        let oldest_journaled = self.journal.front().map(|entry| entry.block.number);
        tracing::warn!(
            reorg_block = reorg_number,
            oldest_journaled = ?oldest_journaled,
            journal_depth = self.config.journal_depth,
            "reactive reorg recovery is incomplete: the reorged block is no longer \
             in the journal, so effects from blocks aged out of the journal are \
             neither rolled back nor purged (the freshness/validation loop is the \
             backstop). Increase ReactiveConfig::journal_depth to recover deeper \
             reorgs precisely."
        );

        self.metrics.deep_reorgs.fetch_add(1, Ordering::Relaxed);

        self.escalate_trust(reorg_number)
    }

    fn record_journal_input(&mut self, block: &BlockRef, input_ref: InputRef) {
        advance_or_enrich_coverage(&mut self.coverage_head, block);
        let entry = self.journal_entry_mut(block);
        let enriched = entry.block;
        if !entry.inputs.contains(&input_ref) {
            entry.inputs.push(input_ref);
        }
        advance_or_enrich_coverage(&mut self.coverage_head, &enriched);
        self.trim_journal();
    }

    fn record_journal_applied(&mut self, block: &BlockRef, applied: AppliedReport<N>) {
        let entry = self.journal_entry_mut(block);
        if !entry.handler_ids.contains(&applied.handler_id) {
            entry.handler_ids.push(applied.handler_id.clone());
        }
        entry.rollback_diffs.push(applied.diff.clone());
        entry.applied.push(applied);
        self.trim_journal();
    }

    fn record_journal_applied_if_present(&mut self, block: &BlockRef, applied: AppliedReport<N>) {
        let Some(entry) = self
            .journal
            .iter_mut()
            .find(|entry| entry.block.number == block.number && entry.block.hash == block.hash)
        else {
            return;
        };
        if !entry.handler_ids.contains(&applied.handler_id) {
            entry.handler_ids.push(applied.handler_id.clone());
        }
        entry.rollback_diffs.push(applied.diff.clone());
        entry.applied.push(applied);
    }

    fn record_journal_resync(&mut self, report: &ResyncReport) {
        if report.diff.is_empty() {
            return;
        }
        let Some(block) = single_hash_pinned_resync_block(report) else {
            return;
        };
        let entry = self.journal_entry_mut(&block);
        entry.rollback_diffs.push(report.diff.clone());
        entry.resynced.push(report.clone());
        self.trim_journal();
    }

    fn journal_entry_mut(&mut self, block: &BlockRef) -> &mut BlockJournal<N> {
        if let Some(index) = self
            .journal
            .iter()
            .position(|entry| entry.block.hash == block.hash && entry.block.number == block.number)
        {
            enrich_block_ref(&mut self.journal[index].block, block);
            return &mut self.journal[index];
        }

        self.journal.push_back(BlockJournal {
            block: *block,
            inputs: Vec::new(),
            applied: Vec::new(),
            handler_ids: Vec::new(),
            resynced: Vec::new(),
            rollback_diffs: Vec::new(),
        });
        let index = self.journal.len() - 1;
        &mut self.journal[index]
    }

    fn trim_journal(&mut self) {
        if self.config.journal_depth == 0 {
            self.journal.clear();
            return;
        }
        while self.journal.len() > self.config.journal_depth {
            self.journal.pop_front();
        }
    }

    fn drain_journal_after(&mut self, index: usize) -> Vec<BlockJournal<N>> {
        self.journal.drain((index + 1)..).collect()
    }

    fn drain_journal_from(&mut self, index: usize) -> Vec<BlockJournal<N>> {
        self.journal.drain(index..).collect()
    }

    fn drain_journal_from_number(&mut self, number: u64) -> Vec<BlockJournal<N>> {
        let Some(index) = self
            .journal
            .iter()
            .position(|entry| entry.block.number >= number)
        else {
            return Vec::new();
        };
        self.drain_journal_from(index)
    }

    fn recover_dropped_journals(
        &mut self,
        cache: &mut EvmCache,
        dropped: Vec<BlockJournal<N>>,
        reason: ReorgReason,
    ) -> Option<ReorgReport<N>> {
        if dropped.is_empty() {
            return None;
        }

        let first_dropped_block = dropped
            .iter()
            .map(|entry| entry.block.number)
            .min()
            .expect("non-empty dropped journal set");
        self.rebase_validation_state_from(first_dropped_block);
        if self
            .safe_head
            .is_some_and(|head| head.number >= first_dropped_block)
        {
            self.safe_head = None;
        }

        let dropped_blocks: Vec<_> = dropped.iter().map(|entry| entry.block).collect();
        let dropped_inputs: Vec<_> = dropped
            .iter()
            .flat_map(|entry| entry.inputs.iter().copied())
            .collect();
        let canceled_resyncs = self.cancel_resyncs_for_dropped_blocks(&dropped_blocks);
        let purge_scopes = purge_scopes_for_dropped_journals(&dropped);
        let rollback_updates = rollback_updates_for_dropped_journals(&dropped, &purge_scopes);
        let purge_updates: Vec<_> = purge_scopes
            .iter()
            .map(|(address, scope)| StateUpdate::purge(*address, scope.clone()))
            .collect();

        let rollback_diff = if rollback_updates.is_empty() {
            StateDiff::default()
        } else {
            cache.apply_updates(&rollback_updates)
        };
        let purge_diff = if purge_updates.is_empty() {
            StateDiff::default()
        } else {
            cache.apply_updates(&purge_updates)
        };
        self.coverage_head = self.journal.back().map(|entry| entry.block);

        Some(ReorgReport {
            dropped: dropped_blocks.first().cloned(),
            dropped_blocks,
            dropped_inputs,
            rollback_updates,
            rollback_diff,
            purge_updates,
            purge_diff,
            canceled_resyncs,
            reason,
            _network: PhantomData,
        })
    }

    fn rebase_validation_state_from(&mut self, first_dropped_block: u64) {
        if let Some(freshness) = self.freshness.as_mut() {
            freshness.invalidate_valid_through_from(first_dropped_block);
        }
        self.tracked_roots
            .retain(|_, baseline| baseline.last_block < first_dropped_block);
        if self
            .last_gate_block
            .is_some_and(|block| block >= first_dropped_block)
        {
            self.last_gate_block = self
                .tracked_roots
                .values()
                .map(|baseline| baseline.last_block)
                .max();
        }
        // Touch provenance is window-relative. Once any block in that window
        // is dropped, retaining the union could incorrectly mark a replacement
        // branch root move as decoder-covered.
        self.touched_since_gate.clear();
    }

    fn cancel_resyncs_for_dropped_blocks(
        &mut self,
        dropped_blocks: &[BlockRef],
    ) -> Vec<ResyncRequest> {
        let mut canceled = Vec::new();
        self.pending_resyncs.retain(|request| {
            let should_cancel = resync_request_targets_dropped_block(request, dropped_blocks);
            if should_cancel {
                canceled.push(request.clone());
            }
            !should_cancel
        });
        canceled
    }

    fn remove_pending_resyncs<'a>(&mut self, ids: impl IntoIterator<Item = &'a ResyncId>) {
        let ids: HashSet<_> = ids.into_iter().cloned().collect();
        self.pending_resyncs
            .retain(|request| !ids.contains(&request.id));
    }
}

/// Validate one provider-neutral delivery envelope without mutating runtime or
/// cache state.
///
/// This is the canonical metadata contract shared by [`ReactiveRuntime`] and
/// composite/remote subscribers. It validates explicit reorg controls before
/// records, canonical record identity and implicit-reorg finality, then
/// progress/barrier/safe/finalized controls. All identity assertions in the
/// envelope must agree at each height. Retained history may be sparse; an
/// explicit common ancestor need not itself be retained when the oldest
/// retained entry is at or below it. Ancestors and removed blocks outside that
/// rollback horizon are rejected, so a durable caller cannot persist a partial
/// rollback. The runtime uses this same implementation with an internal
/// observable-deep-reorg policy for its deliberately non-durable ingest path.
///
/// The returned state and mutations are cache-free. Callers that durably stage
/// delivery should publish/persist them only at their own acknowledgement
/// boundary.
///
/// This validator is deliberately chain-agnostic and does not compare
/// [`ReactiveInputBatch::chain_id`] because [`CanonicalSequenceState`] carries
/// no chain id. Cross-service/composite callers must bind one authoritative
/// chain identity outside this state before sharing or advancing it; runtime
/// ingestion separately checks the batch id against [`EvmCache`].
///
/// # Errors
///
/// Returns [`ReactiveError::InvalidInputRecord`] when record identity/payload
/// metadata is malformed or conflicting, and
/// [`ReactiveError::InvalidChainControl`] when the snapshot or envelope has an
/// invalid canonical transition, incomplete rollback proof, contradictory
/// identity, or invalid coverage/finality relationship.
pub fn validate_canonical_sequence<N: Network>(
    state: &CanonicalSequenceState,
    batch: &ReactiveInputBatch<N>,
) -> Result<CanonicalSequenceValidation, ReactiveError> {
    validate_canonical_sequence_diagnostic(state, batch)
        .map_err(CanonicalSequenceError::into_reactive_error)
}

/// Validate one provider-neutral delivery envelope and retain structured
/// rollback diagnostics.
///
/// This is the diagnostic counterpart to [`validate_canonical_sequence`]. Use
/// it at durable/composite source boundaries that need to distinguish malformed
/// input from an otherwise valid transition whose rollback ancestor has aged
/// out of the retained history. Callers should branch on
/// [`CanonicalSequenceError`] rather than parsing error text.
///
/// # Errors
///
/// Returns [`CanonicalSequenceError::Invalid`] for malformed or contradictory
/// state/input and [`CanonicalSequenceError::IncompleteRollback`] when more
/// retained canonical history is required to prove the transition.
pub fn validate_canonical_sequence_diagnostic<N: Network>(
    state: &CanonicalSequenceState,
    batch: &ReactiveInputBatch<N>,
) -> Result<CanonicalSequenceValidation, CanonicalSequenceError> {
    validate_canonical_sequence_internal(
        state,
        batch,
        CanonicalSequenceValidationPolicy::RequireCompleteRollback,
    )
}

/// Validate a composite-source envelope and normalize harmless coverage
/// overlap.
///
/// This has the same fail-closed rollback/finality/identity contract as
/// [`validate_canonical_sequence`]. In addition, an equal or older
/// [`ChainControl::CanonicalProgress`] whose exact compatible identity is
/// retained is omitted from [`CanonicalSequenceValidation::normalized_chain_controls`].
/// A compatible stale blockful [`ChainControl::Barrier`] is retained with the
/// same opaque id and `block: None`, preserving the synchronization event
/// without forwarding regressive coverage. An equal-height control that fills
/// absent parent/timestamp metadata is retained and applied. Older compatible
/// metadata enrichment is deliberately dropped together with its non-forwarded
/// control so the returned state remains identical to what the runtime will
/// observe. Unknown or conflicting stale identities remain errors.
///
/// # Errors
///
/// Returns [`ReactiveError::InvalidInputRecord`] for malformed or conflicting
/// record identity/payload metadata, and
/// [`ReactiveError::InvalidChainControl`] when canonical overlap cannot be
/// proven redundant or when rollback, adjacency, identity, coverage, or
/// finality validation fails.
pub fn normalize_and_validate_canonical_sequence<N: Network>(
    state: &CanonicalSequenceState,
    batch: &ReactiveInputBatch<N>,
) -> Result<CanonicalSequenceValidation, ReactiveError> {
    normalize_and_validate_canonical_sequence_diagnostic(state, batch)
        .map_err(CanonicalSequenceError::into_reactive_error)
}

/// Validate and normalize one composite-source envelope while retaining
/// structured rollback diagnostics.
///
/// This is the diagnostic counterpart to
/// [`normalize_and_validate_canonical_sequence`]. It has identical transition
/// and normalization semantics, but reports history exhaustion as
/// [`CanonicalSequenceError::IncompleteRollback`] instead of folding it into a
/// prose [`ReactiveError::InvalidChainControl`].
///
/// # Errors
///
/// Returns [`CanonicalSequenceError::Invalid`] for malformed, contradictory, or
/// non-normalizable input and [`CanonicalSequenceError::IncompleteRollback`]
/// when the retained history cannot prove a complete rollback.
pub fn normalize_and_validate_canonical_sequence_diagnostic<N: Network>(
    state: &CanonicalSequenceState,
    batch: &ReactiveInputBatch<N>,
) -> Result<CanonicalSequenceValidation, CanonicalSequenceError> {
    validate_canonical_sequence_internal(
        state,
        batch,
        CanonicalSequenceValidationPolicy::RequireCompleteRollbackNormalizeCoverage,
    )
}

fn validate_canonical_sequence_internal<N: Network>(
    state: &CanonicalSequenceState,
    batch: &ReactiveInputBatch<N>,
    policy: CanonicalSequenceValidationPolicy,
) -> Result<CanonicalSequenceValidation, CanonicalSequenceError> {
    let records = batch
        .records()
        .iter()
        .enumerate()
        .map(|(index, record)| {
            (
                record.clone(),
                DeliveryAudience::All,
                batch
                    .record_delivery_scope(index)
                    .expect("enumerated record always has a delivery scope"),
            )
        })
        .collect::<Vec<_>>();
    let records = sort_scoped_records(dedupe_scoped_records(records)?);
    let records = records
        .iter()
        .map(|(record, _, scope)| (record, *scope))
        .collect::<Vec<_>>();
    validate_canonical_sequence_parts(state, batch.chain_controls(), &records, policy)
}

#[derive(Clone, Copy)]
enum CanonicalSequenceValidationPolicy {
    RequireCompleteRollback,
    RequireCompleteRollbackNormalizeCoverage,
    ObserveIncompleteRollback,
}

/// Stable category for a canonical transition that needs older retained
/// history before it can be durably accepted.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum CanonicalRollbackKind {
    /// An explicit reorg control names an ancestor outside retained history.
    Explicit,
    /// A removed/reorged record names a block outside retained history.
    Removed,
    /// An implicit canonical replacement has no retained parent proof.
    ImplicitParent,
    /// A removed block is not followed by a provable replacement/anchor.
    MissingReplacement,
}

/// Structured failure returned by canonical-sequence diagnostic validation.
///
/// This type is intentionally independent of diagnostic prose so remote and
/// composite subscribers can select recovery behavior without string matching.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum CanonicalSequenceError {
    /// The snapshot or envelope is intrinsically malformed or contradictory.
    #[error(transparent)]
    Invalid(#[from] ReactiveError),
    /// The transition may be valid, but its rollback proof lies outside the
    /// supplied retained canonical history.
    #[error(
        "{kind:?} rollback after block {common_ancestor} exceeds retained canonical history starting at {oldest_retained:?}"
    )]
    IncompleteRollback {
        /// Last ancestor height required to prove the rollback.
        common_ancestor: u64,
        /// Oldest retained canonical height supplied by the caller.
        oldest_retained: Option<u64>,
        /// Stable reason the history window is insufficient.
        kind: CanonicalRollbackKind,
    },
}

#[derive(Clone, Copy, Debug)]
struct RequiredReorgAnchor {
    number: u64,
    block: Option<BlockRef>,
    permits_missing_child_parent: bool,
    must_be_consumed: bool,
}

#[derive(Debug)]
struct SequenceRewind {
    common_ancestor: Option<BlockRef>,
    dropped: Vec<BlockRef>,
}

impl RequiredReorgAnchor {
    const fn hash(self) -> Option<B256> {
        match self.block {
            Some(block) => Some(block.hash),
            None => None,
        }
    }
}

impl CanonicalSequenceError {
    /// Whether retrying with an older retained history window may prove this
    /// same transition.
    pub const fn requires_history(&self) -> bool {
        matches!(self, Self::IncompleteRollback { .. })
    }

    /// Fold this structured diagnostic into the legacy ergonomic runtime error.
    pub fn into_reactive_error(self) -> ReactiveError {
        match self {
            Self::Invalid(error) => error,
            Self::IncompleteRollback {
                common_ancestor,
                oldest_retained,
                kind,
            } => ReactiveError::InvalidChainControl {
                message: format!(
                    "{kind:?} rollback after block {common_ancestor} exceeds retained canonical history starting at {oldest_retained:?}"
                ),
            },
        }
    }
}

impl CanonicalSequenceValidationPolicy {
    const fn requires_complete_rollback(self) -> bool {
        matches!(
            self,
            Self::RequireCompleteRollback | Self::RequireCompleteRollbackNormalizeCoverage
        )
    }

    const fn normalizes_coverage(self) -> bool {
        matches!(self, Self::RequireCompleteRollbackNormalizeCoverage)
    }
}

fn validate_canonical_sequence_parts<N: Network>(
    initial: &CanonicalSequenceState,
    controls: &[ChainControl],
    records: &[(&ReactiveInputRecord<N>, DeliveryScope)],
    policy: CanonicalSequenceValidationPolicy,
) -> Result<CanonicalSequenceValidation, CanonicalSequenceError> {
    validate_canonical_sequence_snapshot(initial)?;
    let control_split = validate_control_phase_order(controls)?;
    let (pre_record_controls, post_record_controls) = controls.split_at(control_split);
    let mut state = initial.clone();
    let mut asserted_blocks = HashMap::<u64, BlockRef>::new();
    let mut mutations = Vec::new();
    let mut normalized_chain_controls = Vec::with_capacity(controls.len());
    let mut batch_dropped = BatchDroppedCanonical::default();
    let mut removed_assertions = HashMap::<(u64, B256), BlockRef>::new();
    let mut removed_heights_by_hash = HashMap::<B256, u64>::new();
    let mut record_proof_control_identities = HashSet::<(u64, B256)>::new();
    let rollback_oldest = initial
        .retained_canonical_history
        .first()
        .map(|block| block.number);

    for control in pre_record_controls {
        normalized_chain_controls.push(control.clone());
        validate_sequence_control(&state, control)?;
        assert_chain_control_identities(&mut asserted_blocks, control)?;
        let ChainControl::Reorg {
            common_ancestor,
            old_tip,
            ..
        } = control
        else {
            unreachable!("phase validation leaves only reorg controls before records")
        };
        let exact_ancestor = state.retained_canonical_history.iter().any(|block| {
            block.number == common_ancestor.number && block.hash == common_ancestor.hash
        });
        let rollback_horizon_covers_ancestor = state
            .retained_canonical_history
            .first()
            .is_some_and(|oldest| oldest.number <= common_ancestor.number);
        if policy.requires_complete_rollback()
            && !exact_ancestor
            && !rollback_horizon_covers_ancestor
        {
            return Err(CanonicalSequenceError::IncompleteRollback {
                common_ancestor: common_ancestor.number,
                oldest_retained: rollback_oldest,
                kind: CanonicalRollbackKind::Explicit,
            });
        }
        let dropped = state
            .retained_canonical_history
            .iter()
            .copied()
            .filter(|block| block.number > common_ancestor.number)
            .collect::<Vec<_>>();
        state
            .retained_canonical_history
            .retain(|block| block.number <= common_ancestor.number);
        upsert_sequence_history(&mut state.retained_canonical_history, common_ancestor)?;
        let mut enriched_ancestor = *common_ancestor;
        if let Some(retained) = state.retained_canonical_history.iter().find(|block| {
            block.number == common_ancestor.number && block.hash == common_ancestor.hash
        }) {
            enrich_block_ref(&mut enriched_ancestor, retained);
        }
        if let Some(coverage) = state.coverage_head.as_ref()
            && coverage.number == common_ancestor.number
            && coverage.hash == common_ancestor.hash
        {
            enrich_block_ref(&mut enriched_ancestor, coverage);
        }
        upsert_sequence_history(&mut state.retained_canonical_history, &enriched_ancestor)?;
        state.coverage_head = Some(enriched_ancestor);
        clear_sequence_heads_above(&mut state, &enriched_ancestor);
        batch_dropped.record_explicit(common_ancestor, old_tip);
        batch_dropped.record_drained(&dropped);
        mutations.push(CanonicalSequenceMutation::Rewind {
            common_ancestor: Some(enriched_ancestor),
            dropped,
        });
    }
    let pre_record_state = state.clone();
    let mut required_reorg_anchor = None::<RequiredReorgAnchor>;

    for (record, scope) in records {
        if !scope.advances_canonical_state() {
            continue;
        }
        if let Some((incoming_dropped_block, _)) = reorg_signal_block(record) {
            let incoming_dropped_block =
                resolve_record_block_payload_metadata(record, incoming_dropped_block)?;
            validate_sequence_matching_metadata(&state, &incoming_dropped_block, "removed record")?;
            validate_sequence_adjacent_parent_identity(
                &state,
                &incoming_dropped_block,
                "removed record",
            )?;
            let mut dropped_block = state
                .retained_canonical_history
                .iter()
                .find(|known| {
                    known.number == incoming_dropped_block.number
                        && known.hash == incoming_dropped_block.hash
                })
                .copied()
                .or_else(|| {
                    state.coverage_head.filter(|known| {
                        known.number == incoming_dropped_block.number
                            && known.hash == incoming_dropped_block.hash
                    })
                })
                .unwrap_or(incoming_dropped_block);
            enrich_block_ref(&mut dropped_block, &incoming_dropped_block);
            validate_sequence_implicit_finality(&state, record, None)?;
            if dropped_block.number == 0 {
                return Err(ReactiveError::InvalidChainControl {
                    message: "a removed/reorged genesis block has no canonical parent anchor"
                        .into(),
                }
                .into());
            }
            let removed_identity = (dropped_block.number, dropped_block.hash);
            if let Some(previous_number) =
                removed_heights_by_hash.insert(dropped_block.hash, dropped_block.number)
                && previous_number != dropped_block.number
            {
                return Err(ReactiveError::InvalidChainControl {
                    message: format!(
                        "removed hash {:?} is reused at heights {} and {}",
                        dropped_block.hash, previous_number, dropped_block.number
                    ),
                }
                .into());
            }
            if let Some(previous) = removed_assertions.get_mut(&removed_identity) {
                if !optional_block_refs_are_compatible(Some(previous), Some(&dropped_block)) {
                    return Err(ReactiveError::InvalidChainControl {
                        message: format!(
                            "duplicate removed block {}:{:?} carries conflicting metadata",
                            dropped_block.number, dropped_block.hash
                        ),
                    }
                    .into());
                }
                enrich_block_ref(previous, &dropped_block);
            } else {
                removed_assertions.insert(removed_identity, dropped_block);
            }
            if asserted_blocks
                .get(&dropped_block.number)
                .is_some_and(|asserted| asserted.hash == dropped_block.hash)
            {
                return Err(ReactiveError::InvalidChainControl {
                    message: format!(
                        "removed block {}:{:?} is asserted canonical by the same envelope",
                        dropped_block.number, dropped_block.hash
                    ),
                }
                .into());
            }
            if batch_dropped.contains(&dropped_block) {
                continue;
            }
            if let Some(index) = state.retained_canonical_history.iter().position(|block| {
                block.number == dropped_block.number && block.hash == dropped_block.hash
            }) {
                let dropped = state.retained_canonical_history.split_off(index);
                batch_dropped.record_drained(&dropped);
                let ancestor_number = dropped_block
                    .number
                    .checked_sub(1)
                    .expect("genesis removal was rejected above");
                let retained_anchor = state
                    .retained_canonical_history
                    .iter()
                    .rev()
                    .find(|head| head.number == ancestor_number)
                    .copied();
                let authenticated_anchor = retained_anchor
                    .or_else(|| {
                        dropped_block.parent_hash.map(|hash| BlockRef {
                            number: ancestor_number,
                            hash,
                            parent_hash: None,
                            timestamp: None,
                        })
                    })
                    .or_else(|| {
                        state
                            .finalized_head
                            .filter(|head| head.number == ancestor_number)
                    });
                let authenticated_anchor = authenticated_anchor.map(|mut anchor| {
                    for head in [state.safe_head.as_ref(), state.finalized_head.as_ref()]
                        .into_iter()
                        .flatten()
                    {
                        if head.number == anchor.number && head.hash == anchor.hash {
                            enrich_block_ref(&mut anchor, head);
                        }
                    }
                    anchor
                });
                required_reorg_anchor = Some(RequiredReorgAnchor {
                    number: ancestor_number,
                    block: authenticated_anchor,
                    permits_missing_child_parent: retained_anchor.is_some(),
                    must_be_consumed: authenticated_anchor.is_none()
                        && state.retained_canonical_history.is_empty(),
                });
                state.coverage_head = authenticated_anchor
                    .or_else(|| state.retained_canonical_history.last().copied());
                if let Some(head) = state.coverage_head {
                    clear_sequence_heads_above(&mut state, &head);
                } else {
                    state.safe_head = None;
                    state.finalized_head = None;
                }
                mutations.push(CanonicalSequenceMutation::Rewind {
                    common_ancestor: state.coverage_head,
                    dropped,
                });
            } else {
                let replacement_is_known = state.retained_canonical_history.iter().any(|block| {
                    block.number == dropped_block.number && block.hash != dropped_block.hash
                }) || state.coverage_head.is_some_and(|head| {
                    head.number == dropped_block.number && head.hash != dropped_block.hash
                });
                if !replacement_is_known {
                    // Ordinary runtime ingestion deliberately keeps an unknown
                    // deep removal observable and lets the recovery path
                    // degrade health. With no exact retained rollback proof,
                    // this validator must not fabricate a new canonical head.
                    if policy.requires_complete_rollback() {
                        return Err(CanonicalSequenceError::IncompleteRollback {
                            common_ancestor: dropped_block
                                .number
                                .checked_sub(1)
                                .expect("genesis removal was rejected above"),
                            oldest_retained: rollback_oldest,
                            kind: CanonicalRollbackKind::Removed,
                        });
                    }
                    continue;
                }
            }
            continue;
        }

        let Some(context_block) = canonical_record_block(record) else {
            continue;
        };
        let incoming_block = resolve_record_block_payload_metadata(record, *context_block)?;
        if post_record_controls
            .iter()
            .filter_map(canonical_coverage_control_block)
            .any(|asserted| {
                asserted.number == incoming_block.number
                    && asserted.hash == incoming_block.hash
                    && optional_block_refs_are_compatible(Some(asserted), Some(&incoming_block))
                    && ((incoming_block.parent_hash.is_none() && asserted.parent_hash.is_some())
                        || (incoming_block.timestamp.is_none() && asserted.timestamp.is_some()))
            })
        {
            record_proof_control_identities.insert((incoming_block.number, incoming_block.hash));
        }
        let mut resolved_block = incoming_block;
        if let Some(asserted) = asserted_blocks
            .get(&incoming_block.number)
            .filter(|asserted| asserted.hash == incoming_block.hash)
        {
            if !optional_block_refs_are_compatible(Some(asserted), Some(&incoming_block)) {
                return Err(ReactiveError::InvalidChainControl {
                    message: format!(
                        "canonical record {}:{:?} conflicts with the same envelope's asserted metadata",
                        incoming_block.number, incoming_block.hash
                    ),
                }
                .into());
            }
            enrich_block_ref(&mut resolved_block, asserted);
        }
        for asserted in post_record_controls
            .iter()
            .filter_map(chain_control_canonical_assertion)
            .filter(|asserted| {
                asserted.number == incoming_block.number && asserted.hash == incoming_block.hash
            })
        {
            if !optional_block_refs_are_compatible(Some(&resolved_block), Some(asserted)) {
                return Err(ReactiveError::InvalidChainControl {
                    message: format!(
                        "canonical record {}:{:?} conflicts with the same envelope's asserted metadata",
                        incoming_block.number, incoming_block.hash
                    ),
                }
                .into());
            }
            enrich_block_ref(&mut resolved_block, asserted);
        }
        let replacement_anchor =
            required_reorg_anchor.filter(|required| resolved_block.number > required.number);
        if resolved_block.parent_hash.is_none()
            && replacement_anchor.is_some_and(|anchor| {
                anchor.permits_missing_child_parent
                    && anchor.number.checked_add(1) == Some(resolved_block.number)
            })
        {
            resolved_block.parent_hash = replacement_anchor.and_then(RequiredReorgAnchor::hash);
        }
        let block = &resolved_block;
        if removed_assertions.contains_key(&(block.number, block.hash)) {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical block {}:{:?} is also removed by the same envelope",
                    block.number, block.hash
                ),
            }
            .into());
        }
        if let Some(removed_number) = removed_heights_by_hash.get(&block.hash)
            && *removed_number != block.number
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical hash {:?} at height {} is removed at height {} by the same envelope",
                    block.hash, block.number, removed_number
                ),
            }
            .into());
        }
        let replacement_proven_by_removal =
            validate_replacement_reorg_anchor(replacement_anchor, block, policy, rollback_oldest)?;
        if replacement_anchor.is_some() {
            required_reorg_anchor = None;
        }
        validate_sequence_matching_metadata(&state, block, "canonical record")?;
        validate_sequence_implicit_finality(&state, record, Some(block))?;
        let implicit_replacement_requires_history = if replacement_proven_by_removal {
            false
        } else {
            sequence_implicit_replacement_requires_history(&state, block, policy)?
        };
        if implicit_replacement_requires_history && policy.requires_complete_rollback() {
            return Err(CanonicalSequenceError::IncompleteRollback {
                common_ancestor: block.number.saturating_sub(1),
                oldest_retained: rollback_oldest,
                kind: CanonicalRollbackKind::ImplicitParent,
            });
        }
        assert_canonical_block_identity(&mut asserted_blocks, block, "canonical record")?;
        let allow_parentless_extension = replacement_anchor.is_some_and(|anchor| {
            anchor.permits_missing_child_parent
                && anchor.number.checked_add(1) == Some(block.number)
        });
        if let Some(rewind) =
            apply_sequence_canonical_block(&mut state, block, allow_parentless_extension)?
        {
            mutations.push(CanonicalSequenceMutation::Rewind {
                common_ancestor: rewind.common_ancestor,
                dropped: rewind.dropped,
            });
        }
        mutations.push(CanonicalSequenceMutation::Canonical(*block));
    }

    for control in post_record_controls {
        if let Some(block) = chain_control_canonical_assertion(control)
            && removed_assertions.contains_key(&(block.number, block.hash))
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical block {}:{:?} is also removed by the same envelope",
                    block.number, block.hash
                ),
            }
            .into());
        }
        if let Some(block) = chain_control_canonical_assertion(control)
            && let Some(removed_number) = removed_heights_by_hash.get(&block.hash)
            && *removed_number != block.number
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical hash {:?} at height {} is removed at height {} by the same envelope",
                    block.hash, block.number, removed_number
                ),
            }
            .into());
        }
        let replacement_anchor = canonical_coverage_control_block(control).and_then(|block| {
            required_reorg_anchor.filter(|required| block.number > required.number)
        });
        if let Some(block) = canonical_coverage_control_block(control) {
            validate_replacement_reorg_anchor(replacement_anchor, block, policy, rollback_oldest)?;
            if replacement_anchor.is_some() {
                required_reorg_anchor = None;
            }
        }
        assert_chain_control_identities(&mut asserted_blocks, control)?;
        let preserves_record_proof =
            canonical_coverage_control_block(control).is_some_and(|block| {
                record_proof_control_identities.contains(&(block.number, block.hash))
            });
        if policy.normalizes_coverage()
            && !preserves_record_proof
            && let Some(block) = canonical_coverage_control_block(control)
            && state
                .coverage_head
                .is_some_and(|head| block.number <= head.number)
        {
            let is_equal_coverage = state
                .coverage_head
                .is_some_and(|head| block.number == head.number);
            let known = state
                .coverage_head
                .as_ref()
                .filter(|head| head.number == block.number && head.hash == block.hash)
                .or_else(|| {
                    state
                        .retained_canonical_history
                        .iter()
                        .find(|entry| entry.number == block.number && entry.hash == block.hash)
                });
            if let Some(known) = known
                && optional_block_refs_are_compatible(Some(known), Some(block))
                && (!is_equal_coverage || !sequence_block_adds_metadata(&state, block))
            {
                if let ChainControl::Barrier { id, .. } = control {
                    normalized_chain_controls.push(ChainControl::Barrier {
                        id: id.clone(),
                        block: None,
                    });
                }
                continue;
            }
        }
        validate_sequence_control(&state, control)?;
        normalized_chain_controls.push(control.clone());
        match control {
            ChainControl::Safe(block) => {
                set_or_enrich_block_ref(&mut state.safe_head, block);
                mutations.push(CanonicalSequenceMutation::Safe(
                    state.safe_head.expect("safe head was just installed"),
                ));
            }
            ChainControl::Finalized(block) => {
                set_or_enrich_block_ref(&mut state.finalized_head, block);
                mutations.push(CanonicalSequenceMutation::Finalized(
                    state
                        .finalized_head
                        .expect("finalized head was just installed"),
                ));
            }
            ChainControl::CanonicalProgress(block)
            | ChainControl::Barrier {
                block: Some(block), ..
            } => {
                let allow_parentless_extension = replacement_anchor.is_some_and(|anchor| {
                    anchor.permits_missing_child_parent
                        && anchor.number.checked_add(1) == Some(block.number)
                }) || (replacement_anchor.is_none()
                    && block.parent_hash.is_none()
                    && state
                        .coverage_head
                        .is_some_and(|head| head.number.checked_add(1) == Some(block.number)));
                if let Some(rewind) =
                    apply_sequence_canonical_block(&mut state, block, allow_parentless_extension)?
                {
                    mutations.push(CanonicalSequenceMutation::Rewind {
                        common_ancestor: rewind.common_ancestor,
                        dropped: rewind.dropped,
                    });
                }
                mutations.push(CanonicalSequenceMutation::Canonical(*block));
            }
            ChainControl::Barrier { block: None, .. } => {}
            ChainControl::Reorg { .. } => {
                unreachable!("phase validation excludes post-record reorg controls")
            }
        }
    }

    if let Some(required) = required_reorg_anchor
        && required.must_be_consumed
        && policy.requires_complete_rollback()
    {
        return Err(CanonicalSequenceError::IncompleteRollback {
            common_ancestor: required.number,
            oldest_retained: rollback_oldest,
            kind: CanonicalRollbackKind::MissingReplacement,
        });
    }

    validate_canonical_sequence_snapshot(&state)?;
    Ok(CanonicalSequenceValidation {
        pre_record_state,
        next_state: state,
        mutations,
        normalized_chain_controls,
    })
}

fn validate_canonical_sequence_snapshot(
    state: &CanonicalSequenceState,
) -> Result<(), ReactiveError> {
    let invalid = |message: String| ReactiveError::InvalidChainControl { message };
    let supplied_blocks = state
        .retained_canonical_history
        .iter()
        .chain(state.coverage_head.iter())
        .chain(state.safe_head.iter())
        .chain(state.finalized_head.iter())
        .collect::<Vec<_>>();
    validate_known_parent_hash_heights(&supplied_blocks)?;
    let mut prior = None::<BlockRef>;
    for block in &state.retained_canonical_history {
        if let Some(previous) = prior {
            if block.number < previous.number {
                return Err(invalid(
                    "retained canonical history is not ordered by block number".into(),
                ));
            }
            if block.number == previous.number {
                let qualifier = if optional_block_refs_are_compatible(Some(&previous), Some(block))
                {
                    "duplicate"
                } else {
                    "conflicting"
                };
                return Err(invalid(format!(
                    "retained canonical history contains {qualifier} identities at block {}",
                    block.number
                )));
            }
            if previous.number.checked_add(1) == Some(block.number)
                && block.parent_hash.is_some()
                && block.parent_hash != Some(previous.hash)
            {
                return Err(invalid(format!(
                    "adjacent retained block {}:{:?} does not descend from {}:{:?}",
                    block.number, block.hash, previous.number, previous.hash
                )));
            }
        }
        prior = Some(*block);
    }
    if state.coverage_head.is_none() && !state.retained_canonical_history.is_empty() {
        return Err(invalid(
            "retained canonical history requires an authoritative coverage head".into(),
        ));
    }
    if let Some(head) = state.coverage_head.as_ref() {
        if let Some(retained) = state
            .retained_canonical_history
            .iter()
            .find(|entry| entry.number == head.number)
            && !optional_block_refs_are_compatible(Some(retained), Some(head))
        {
            return Err(invalid(format!(
                "coverage head {}:{:?} conflicts with retained identity {:?}",
                head.number, head.hash, retained
            )));
        }
        if state
            .retained_canonical_history
            .last()
            .is_some_and(|retained| retained.number > head.number)
        {
            return Err(invalid(
                "retained canonical history advances beyond the coverage head".into(),
            ));
        }
        if let Some(retained) = state.retained_canonical_history.last()
            && retained.number.checked_add(1) == Some(head.number)
            && head.parent_hash.is_some()
            && head.parent_hash != Some(retained.hash)
        {
            return Err(invalid(format!(
                "coverage head {}:{:?} does not descend from adjacent retained block {}:{:?}",
                head.number, head.hash, retained.number, retained.hash
            )));
        }
    }
    if let Some(safe) = state.safe_head.as_ref() {
        validate_sequence_known_identity(state, safe, "safe")?;
        validate_sequence_head_within_coverage(state, safe, "safe")?;
        validate_coverage_descends_from_adjacent_head(state.coverage_head.as_ref(), safe, "safe")?;
    }
    if let Some(finalized) = state.finalized_head.as_ref() {
        validate_sequence_known_identity(state, finalized, "finalized")?;
        validate_sequence_head_within_coverage(state, finalized, "finalized")?;
        validate_coverage_descends_from_adjacent_head(
            state.coverage_head.as_ref(),
            finalized,
            "finalized",
        )?;
    }
    validate_adjacent_finality(state.finalized_head.as_ref(), state.safe_head.as_ref())?;
    if let (Some(finalized), Some(safe)) = (state.finalized_head, state.safe_head)
        && (finalized.number > safe.number
            || (finalized.number == safe.number && finalized.hash != safe.hash))
    {
        return Err(invalid(
            "finalized head cannot advance beyond or conflict with safe head".into(),
        ));
    }
    Ok(())
}

fn validate_known_parent_hash_heights(blocks: &[&BlockRef]) -> Result<(), ReactiveError> {
    let mut heights_by_hash = HashMap::<B256, u64>::with_capacity(blocks.len());
    let mut resolved_by_height = HashMap::<u64, BlockRef>::with_capacity(blocks.len());
    for block in blocks.iter().copied() {
        if let Some(previous_height) = heights_by_hash.insert(block.hash, block.number)
            && previous_height != block.number
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical hash {:?} is reused at heights {} and {}",
                    block.hash, previous_height, block.number
                ),
            });
        }
        if let Some(resolved) = resolved_by_height.get_mut(&block.number) {
            if !optional_block_refs_are_compatible(Some(resolved), Some(block)) {
                return Err(ReactiveError::InvalidChainControl {
                    message: format!(
                        "canonical aliases at height {} carry conflicting identities or metadata",
                        block.number
                    ),
                });
            }
            enrich_block_ref(resolved, block);
        } else {
            resolved_by_height.insert(block.number, *block);
        }
    }
    for child in resolved_by_height.values() {
        let Some(parent_hash) = child.parent_hash else {
            continue;
        };
        if let Some(parent_number) = heights_by_hash.get(&parent_hash)
            && parent_number.checked_add(1) != Some(child.number)
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "block {}:{:?} names hash {:?} from known height {} as a non-adjacent parent",
                    child.number, child.hash, parent_hash, parent_number
                ),
            });
        }
        if let Some(parent_number) = child.number.checked_sub(1)
            && let Some(parent) = resolved_by_height.get(&parent_number)
            && parent.hash != parent_hash
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "block {}:{:?} does not descend from supplied adjacent identity {}:{:?}",
                    child.number, child.hash, parent.number, parent.hash
                ),
            });
        }
    }
    Ok(())
}

fn validate_coverage_descends_from_adjacent_head(
    coverage: Option<&BlockRef>,
    head: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    let Some(coverage) = coverage else {
        return Ok(());
    };
    if head.number.checked_add(1) == Some(coverage.number)
        && coverage
            .parent_hash
            .is_some_and(|parent| parent != head.hash)
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "canonical coverage {}:{:?} does not descend from adjacent {label} head {}:{:?}",
                coverage.number, coverage.hash, head.number, head.hash
            ),
        });
    }
    Ok(())
}

fn validate_sequence_control(
    state: &CanonicalSequenceState,
    control: &ChainControl,
) -> Result<(), ReactiveError> {
    let invalid = |message: String| ReactiveError::InvalidChainControl { message };
    match control {
        ChainControl::Safe(block) => {
            validate_sequence_known_identity(state, block, "safe")?;
            validate_sequence_head_within_coverage(state, block, "safe")?;
            if let Some(current) = state.safe_head.as_ref()
                && (block.number < current.number
                    || (block.number == current.number
                        && (block.hash != current.hash
                            || !optional_block_refs_are_compatible(Some(block), Some(current)))))
            {
                return Err(invalid(format!(
                    "safe head {}:{:?} conflicts with current {}:{:?}",
                    block.number, block.hash, current.number, current.hash
                )));
            }
            if let Some(finalized) = state.finalized_head.as_ref()
                && (block.number < finalized.number
                    || (block.number == finalized.number && block.hash != finalized.hash))
            {
                return Err(invalid(
                    "safe head cannot precede or conflict with finalized head".into(),
                ));
            }
            validate_adjacent_finality(state.finalized_head.as_ref(), Some(block))?;
        }
        ChainControl::Finalized(block) => {
            validate_sequence_known_identity(state, block, "finalized")?;
            validate_sequence_head_within_coverage(state, block, "finalized")?;
            if let Some(current) = state.finalized_head.as_ref()
                && (block.number < current.number
                    || (block.number == current.number
                        && (block.hash != current.hash
                            || !optional_block_refs_are_compatible(Some(block), Some(current)))))
            {
                return Err(invalid(format!(
                    "finalized head {}:{:?} conflicts with current {}:{:?}",
                    block.number, block.hash, current.number, current.hash
                )));
            }
            if let Some(safe) = state.safe_head.as_ref()
                && (block.number > safe.number
                    || (block.number == safe.number && block.hash != safe.hash))
            {
                return Err(invalid(
                    "finalized head cannot advance beyond or conflict with safe head".into(),
                ));
            }
            validate_adjacent_finality(Some(block), state.safe_head.as_ref())?;
        }
        ChainControl::CanonicalProgress(block)
        | ChainControl::Barrier {
            block: Some(block), ..
        } => {
            validate_sequence_known_identity(state, block, "canonical coverage")?;
            if let Some(current) = state.coverage_head.as_ref()
                && (block.number < current.number
                    || (block.number == current.number && block.hash != current.hash))
            {
                return Err(invalid(format!(
                    "canonical coverage {}:{:?} conflicts with current {}:{:?}",
                    block.number, block.hash, current.number, current.hash
                )));
            }
            if let Some(current) = state.coverage_head.as_ref()
                && current.number.checked_add(1) == Some(block.number)
                && block.parent_hash.is_some()
                && block.parent_hash != Some(current.hash)
            {
                return Err(invalid(format!(
                    "canonical coverage {}:{:?} does not descend from current {}:{:?}",
                    block.number, block.hash, current.number, current.hash
                )));
            }
        }
        ChainControl::Barrier { block: None, .. } => {}
        ChainControl::Reorg {
            common_ancestor,
            old_tip,
            new_tip,
        } => {
            validate_sequence_known_identity(state, common_ancestor, "reorg common ancestor")?;
            validate_reorg_ancestor_against_retained_branch(state, common_ancestor)?;
            validate_sequence_known_hash_height(state, old_tip, "reorg old tip")?;
            validate_sequence_known_hash_height(state, new_tip, "reorg new tip")?;
            validate_sequence_known_parent_height(state, old_tip, "reorg old tip")?;
            validate_sequence_known_parent_height(state, new_tip, "reorg new tip")?;
            validate_sequence_adjacent_parent_identity(state, old_tip, "reorg old tip")?;
            if let Some(current) = state.coverage_head.as_ref()
                && (old_tip.number != current.number
                    || old_tip.hash != current.hash
                    || !optional_block_refs_are_compatible(Some(old_tip), Some(current)))
            {
                return Err(invalid(format!(
                    "reorg old tip {}:{:?} does not exactly match current metadata {}:{:?}",
                    old_tip.number, old_tip.hash, current.number, current.hash
                )));
            }
            if common_ancestor.number > old_tip.number || common_ancestor.number > new_tip.number {
                return Err(invalid(
                    "reorg common ancestor cannot be above either branch tip".into(),
                ));
            }
            if common_ancestor.number == old_tip.number || common_ancestor.number == new_tip.number
            {
                return Err(invalid(
                    "reorg must replace non-empty old and new branches above the common ancestor"
                        .into(),
                ));
            }
            if old_tip.number == new_tip.number && old_tip.hash == new_tip.hash {
                return Err(invalid(
                    "reorg old and new tips cannot have the same canonical identity".into(),
                ));
            }
            for (label, tip) in [("old", old_tip), ("new", new_tip)] {
                if common_ancestor.number.checked_add(1) == Some(tip.number)
                    && tip.parent_hash != Some(common_ancestor.hash)
                {
                    return Err(invalid(format!(
                        "reorg {label} tip does not descend from the common ancestor"
                    )));
                }
            }
            if let Some(finalized) = state.finalized_head.as_ref()
                && (common_ancestor.number < finalized.number
                    || (common_ancestor.number == finalized.number
                        && common_ancestor.hash != finalized.hash))
            {
                return Err(invalid(
                    "reorg would cross or conflict with the finalized head".into(),
                ));
            }
        }
    }
    Ok(())
}

fn validate_sequence_known_identity(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    validate_sequence_known_hash_height(state, block, label)?;
    validate_sequence_known_parent_height(state, block, label)?;
    let known = state
        .coverage_head
        .as_ref()
        .filter(|head| head.number == block.number)
        .or_else(|| {
            state
                .retained_canonical_history
                .iter()
                .find(|entry| entry.number == block.number)
        });
    if let Some(known) = known
        && !optional_block_refs_are_compatible(Some(known), Some(block))
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} block {}:{:?} conflicts with known canonical block {:?}",
                block.number, block.hash, known
            ),
        });
    }
    Ok(())
}

fn validate_sequence_known_parent_height(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    let Some(parent_hash) = block.parent_hash else {
        return Ok(());
    };
    let known_parent = state
        .retained_canonical_history
        .iter()
        .chain(state.coverage_head.iter())
        .chain(state.safe_head.iter())
        .chain(state.finalized_head.iter())
        .find(|known| known.hash == parent_hash);
    if let Some(parent) = known_parent
        && parent.number.checked_add(1) != Some(block.number)
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} block {}:{:?} names hash {:?} from known height {} as a non-adjacent parent",
                block.number, block.hash, parent.hash, parent.number
            ),
        });
    }
    Ok(())
}

fn validate_sequence_head_within_coverage(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    let Some(coverage) = state.coverage_head.as_ref() else {
        return Err(ReactiveError::InvalidChainControl {
            message: format!("{label} head requires an authoritative coverage head"),
        });
    };
    if block.number > coverage.number
        || (block.number == coverage.number
            && !optional_block_refs_are_compatible(Some(block), Some(coverage)))
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} head {}:{:?} advances beyond or conflicts with coverage {}:{:?}",
                block.number, block.hash, coverage.number, coverage.hash
            ),
        });
    }
    Ok(())
}

fn validate_sequence_matching_metadata(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    validate_sequence_known_hash_height(state, block, label)?;
    validate_sequence_known_parent_height(state, block, label)?;
    let known = state
        .coverage_head
        .as_ref()
        .filter(|head| head.number == block.number && head.hash == block.hash)
        .or_else(|| {
            state
                .retained_canonical_history
                .iter()
                .find(|entry| entry.number == block.number && entry.hash == block.hash)
        });
    if let Some(known) = known
        && !optional_block_refs_are_compatible(Some(known), Some(block))
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} block {}:{:?} carries metadata conflicting with known canonical block {:?}",
                block.number, block.hash, known
            ),
        });
    }
    Ok(())
}

fn validate_sequence_known_hash_height(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    let known = state
        .retained_canonical_history
        .iter()
        .chain(state.coverage_head.iter())
        .chain(state.safe_head.iter())
        .chain(state.finalized_head.iter())
        .find(|known| known.hash == block.hash);
    if let Some(known) = known
        && known.number != block.number
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} block {}:{:?} reuses a canonical hash already known at height {}",
                block.number, block.hash, known.number
            ),
        });
    }
    Ok(())
}

fn validate_reorg_ancestor_against_retained_branch(
    state: &CanonicalSequenceState,
    ancestor: &BlockRef,
) -> Result<(), ReactiveError> {
    let adjacent_number = ancestor.number.checked_add(1);
    for retained in state
        .retained_canonical_history
        .iter()
        .chain(state.coverage_head.iter())
        .chain(state.safe_head.iter())
        .chain(state.finalized_head.iter())
    {
        if Some(retained.number) == adjacent_number
            && retained
                .parent_hash
                .is_some_and(|parent| parent != ancestor.hash)
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "reorg common ancestor {}:{:?} conflicts with retained child {}:{:?} parent {:?}",
                    ancestor.number,
                    ancestor.hash,
                    retained.number,
                    retained.hash,
                    retained.parent_hash
                ),
            });
        }
        if retained.parent_hash == Some(ancestor.hash) && Some(retained.number) != adjacent_number {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "reorg common ancestor {}:{:?} is named as the non-adjacent parent of retained block {}:{:?}",
                    ancestor.number, ancestor.hash, retained.number, retained.hash
                ),
            });
        }
    }
    Ok(())
}

fn validate_sequence_adjacent_parent_identity(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    let Some(parent_hash) = block.parent_hash else {
        return Ok(());
    };
    let Some(parent_number) = block.number.checked_sub(1) else {
        return Ok(());
    };
    let known_parent = state
        .retained_canonical_history
        .iter()
        .chain(state.coverage_head.iter())
        .chain(state.safe_head.iter())
        .chain(state.finalized_head.iter())
        .find(|known| known.number == parent_number);
    if let Some(known_parent) = known_parent
        && known_parent.hash != parent_hash
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "{label} block {}:{:?} names parent {:?}, which conflicts with known adjacent block {}:{:?}",
                block.number, block.hash, parent_hash, known_parent.number, known_parent.hash
            ),
        });
    }
    Ok(())
}

fn sequence_block_adds_metadata(state: &CanonicalSequenceState, incoming: &BlockRef) -> bool {
    state
        .coverage_head
        .iter()
        .chain(state.retained_canonical_history.iter())
        .filter(|known| known.number == incoming.number && known.hash == incoming.hash)
        .any(|known| {
            (known.parent_hash.is_none() && incoming.parent_hash.is_some())
                || (known.timestamp.is_none() && incoming.timestamp.is_some())
        })
}

fn validate_sequence_implicit_finality<N: Network>(
    state: &CanonicalSequenceState,
    record: &ReactiveInputRecord<N>,
    resolved_canonical_block: Option<&BlockRef>,
) -> Result<(), ReactiveError> {
    let Some(finalized) = state.finalized_head.as_ref() else {
        return Ok(());
    };
    if let Some((dropped, _)) = reorg_signal_block(record) {
        if dropped.number <= finalized.number {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "implicit reorg at {}:{:?} would cross finalized head {}:{:?}",
                    dropped.number, dropped.hash, finalized.number, finalized.hash
                ),
            });
        }
        return Ok(());
    }
    let Some(block) = resolved_canonical_block.or_else(|| canonical_record_block(record)) else {
        return Ok(());
    };
    let Some(latest) = state.coverage_head.as_ref() else {
        return Ok(());
    };
    if (block.number == latest.number && block.hash == latest.hash)
        || state
            .retained_canonical_history
            .iter()
            .any(|entry| entry.number == block.number && entry.hash == block.hash)
        || (latest.number.checked_add(1) == Some(block.number)
            && block.parent_hash == Some(latest.hash))
        || latest
            .number
            .checked_add(1)
            .is_some_and(|next| block.number > next)
    {
        return Ok(());
    }
    let crosses_finalized = if block.number <= finalized.number {
        true
    } else if let Some(parent_hash) = block.parent_hash {
        if finalized.number.checked_add(1) == Some(block.number) && parent_hash == finalized.hash {
            false
        } else if let Some(parent_index) =
            state.retained_canonical_history.iter().rposition(|entry| {
                entry.number.checked_add(1) == Some(block.number) && entry.hash == parent_hash
            })
        {
            state
                .retained_canonical_history
                .iter()
                .skip(parent_index + 1)
                .any(|entry| entry.number <= finalized.number)
        } else {
            true
        }
    } else {
        true
    };
    if crosses_finalized {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "canonical input {}:{:?} would replace finalized head {}:{:?}",
                block.number, block.hash, finalized.number, finalized.hash
            ),
        });
    }
    Ok(())
}

fn validate_required_reorg_anchor(
    required: Option<RequiredReorgAnchor>,
    block: &BlockRef,
) -> Result<(), ReactiveError> {
    let Some(required) = required else {
        return Ok(());
    };
    let ancestor_hash = required.hash();
    let restores_ancestor =
        block.number == required.number && ancestor_hash.is_some_and(|hash| block.hash == hash);
    let replaces_removed_child = required.number.checked_add(1) == Some(block.number)
        && ancestor_hash.is_some()
        && (block.parent_hash == ancestor_hash
            || (block.parent_hash.is_none() && required.permits_missing_child_parent));
    if restores_ancestor || replaces_removed_child {
        return Ok(());
    }
    Err(ReactiveError::InvalidChainControl {
        message: format!(
            "canonical replacement {}:{:?} does not prove the removed tip's parent at block {}",
            block.number, block.hash, required.number
        ),
    })
}

fn validate_replacement_reorg_anchor(
    required: Option<RequiredReorgAnchor>,
    block: &BlockRef,
    policy: CanonicalSequenceValidationPolicy,
    oldest_retained: Option<u64>,
) -> Result<bool, CanonicalSequenceError> {
    let Some(required) = required else {
        return Ok(false);
    };
    match validate_required_reorg_anchor(Some(required), block) {
        Ok(()) => Ok(true),
        Err(error) if required.block.is_some() => Err(error.into()),
        Err(_) if policy.requires_complete_rollback() => {
            Err(CanonicalSequenceError::IncompleteRollback {
                common_ancestor: required.number,
                oldest_retained,
                kind: CanonicalRollbackKind::MissingReplacement,
            })
        }
        Err(_) => Ok(false),
    }
}

fn apply_sequence_canonical_block(
    state: &mut CanonicalSequenceState,
    block: &BlockRef,
    allow_parentless_adjacent_extension: bool,
) -> Result<Option<SequenceRewind>, ReactiveError> {
    let latest = state.coverage_head;
    let already_known = state
        .retained_canonical_history
        .iter()
        .any(|entry| entry.number == block.number && entry.hash == block.hash);
    let repeats_tip =
        latest.is_some_and(|head| head.number == block.number && head.hash == block.hash);
    let extends_tip = latest.is_some_and(|head| {
        head.number.checked_add(1) == Some(block.number)
            && (block.parent_hash == Some(head.hash)
                || (allow_parentless_adjacent_extension && block.parent_hash.is_none()))
    });
    let forward_gap = latest.is_some_and(|head| {
        head.number
            .checked_add(1)
            .is_some_and(|next| block.number > next)
    });
    let mut rewind = None;

    if latest.is_some() && !already_known && !repeats_tip && !extends_tip && !forward_gap {
        let retained_parent = block.parent_hash.and_then(|parent_hash| {
            state
                .retained_canonical_history
                .iter()
                .rposition(|entry| {
                    entry.number.checked_add(1) == Some(block.number) && entry.hash == parent_hash
                })
                .map(|index| (index, state.retained_canonical_history[index]))
        });
        let finalized_parent = block.parent_hash.and_then(|parent_hash| {
            state.finalized_head.filter(|finalized| {
                finalized.number.checked_add(1) == Some(block.number)
                    && finalized.hash == parent_hash
            })
        });
        let (common_ancestor, dropped) = if let Some((parent_index, parent)) = retained_parent {
            let dropped = state.retained_canonical_history.split_off(parent_index + 1);
            (Some(parent), dropped)
        } else if let Some(finalized) = finalized_parent {
            let dropped = state
                .retained_canonical_history
                .iter()
                .position(|entry| entry.number > finalized.number)
                .map_or_else(Vec::new, |index| {
                    state.retained_canonical_history.split_off(index)
                });
            (Some(finalized), dropped)
        } else {
            // The observable runtime policy may continue after an incomplete
            // rollback proof so it can degrade health and repair. The metadata
            // validator must nevertheless avoid claiming any old prefix is an
            // ancestor of the arriving branch: without the exact N-1 parent,
            // no retained identity is authenticated.
            (None, std::mem::take(&mut state.retained_canonical_history))
        };
        state.coverage_head = common_ancestor;
        if let Some(common_ancestor) = common_ancestor {
            clear_sequence_heads_above(state, &common_ancestor);
        } else {
            state.safe_head = None;
            state.finalized_head = None;
        }
        rewind = Some(SequenceRewind {
            common_ancestor,
            dropped,
        });
    }
    upsert_sequence_history(&mut state.retained_canonical_history, block)?;
    advance_or_enrich_coverage(&mut state.coverage_head, block);
    Ok(rewind)
}

fn sequence_implicit_replacement_requires_history(
    state: &CanonicalSequenceState,
    block: &BlockRef,
    policy: CanonicalSequenceValidationPolicy,
) -> Result<bool, ReactiveError> {
    let Some(latest) = state.coverage_head else {
        return Ok(false);
    };
    let already_known = state
        .retained_canonical_history
        .iter()
        .any(|entry| entry.number == block.number && entry.hash == block.hash);
    let repeats_tip = block.number == latest.number && block.hash == latest.hash;
    let extends_tip = latest.number.checked_add(1) == Some(block.number)
        && block.parent_hash == Some(latest.hash);
    let forward_gap = latest
        .number
        .checked_add(1)
        .is_some_and(|next| block.number > next);
    if already_known || repeats_tip || extends_tip || forward_gap {
        return Ok(false);
    }
    let Some(parent_hash) = block.parent_hash else {
        if policy.requires_complete_rollback() {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "implicit canonical replacement {}:{:?} must identify its parent",
                    block.number, block.hash
                ),
            });
        }
        return Ok(true);
    };
    let known_adjacent_parent = block.number.checked_sub(1).and_then(|parent_number| {
        state
            .retained_canonical_history
            .iter()
            .chain(state.coverage_head.iter())
            .chain(state.safe_head.iter())
            .chain(state.finalized_head.iter())
            .find(|known| known.number == parent_number)
    });
    if let Some(known_parent) = known_adjacent_parent
        && known_parent.hash != parent_hash
        && policy.requires_complete_rollback()
    {
        return Err(ReactiveError::InvalidChainControl {
            message: format!(
                "implicit canonical replacement {}:{:?} names parent {:?}, which conflicts with known adjacent block {}:{:?}",
                block.number, block.hash, parent_hash, known_parent.number, known_parent.hash
            ),
        });
    }
    let retained_parent = state.retained_canonical_history.iter().any(|entry| {
        entry.number.checked_add(1) == Some(block.number) && entry.hash == parent_hash
    });
    let finalized_parent = state.finalized_head.is_some_and(|finalized| {
        finalized.number.checked_add(1) == Some(block.number) && parent_hash == finalized.hash
    });
    Ok(!retained_parent && !finalized_parent)
}

fn upsert_sequence_history(
    history: &mut Vec<BlockRef>,
    block: &BlockRef,
) -> Result<(), ReactiveError> {
    if let Some(existing) = history
        .iter_mut()
        .find(|entry| entry.number == block.number)
    {
        if existing.hash != block.hash {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical block {}:{:?} conflicts with retained identity {:?}",
                    block.number, block.hash, existing
                ),
            });
        }
        if !optional_block_refs_are_compatible(Some(existing), Some(block)) {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "canonical block {}:{:?} carries conflicting retained metadata",
                    block.number, block.hash
                ),
            });
        }
        enrich_block_ref(existing, block);
    } else {
        history.push(*block);
        history.sort_by_key(|entry| entry.number);
    }
    Ok(())
}

fn clear_sequence_heads_above(state: &mut CanonicalSequenceState, ancestor: &BlockRef) {
    if state.safe_head.as_ref().is_some_and(|head| {
        head.number > ancestor.number
            || (head.number == ancestor.number && head.hash != ancestor.hash)
    }) {
        state.safe_head = None;
    }
    if state.finalized_head.as_ref().is_some_and(|head| {
        head.number > ancestor.number
            || (head.number == ancestor.number && head.hash != ancestor.hash)
    }) {
        state.finalized_head = None;
    }
}

fn validate_control_phase_order(controls: &[ChainControl]) -> Result<usize, ReactiveError> {
    let split = controls
        .iter()
        .position(|control| !matches!(control, ChainControl::Reorg { .. }))
        .unwrap_or(controls.len());
    if controls[split..]
        .iter()
        .any(|control| matches!(control, ChainControl::Reorg { .. }))
    {
        return Err(ReactiveError::InvalidChainControl {
            message: "reorg controls must precede records and all post-record controls in a batch"
                .into(),
        });
    }
    Ok(split)
}

fn canonical_coverage_control_block(control: &ChainControl) -> Option<&BlockRef> {
    match control {
        ChainControl::CanonicalProgress(block)
        | ChainControl::Barrier {
            block: Some(block), ..
        } => Some(block),
        ChainControl::Reorg { .. }
        | ChainControl::Safe(_)
        | ChainControl::Finalized(_)
        | ChainControl::Barrier { block: None, .. } => None,
    }
}

fn chain_control_canonical_assertion(control: &ChainControl) -> Option<&BlockRef> {
    match control {
        ChainControl::Safe(block)
        | ChainControl::Finalized(block)
        | ChainControl::CanonicalProgress(block)
        | ChainControl::Barrier {
            block: Some(block), ..
        } => Some(block),
        ChainControl::Reorg { .. } | ChainControl::Barrier { block: None, .. } => None,
    }
}

fn assert_chain_control_identities(
    asserted_blocks: &mut HashMap<u64, BlockRef>,
    control: &ChainControl,
) -> Result<(), ReactiveError> {
    match control {
        ChainControl::Safe(block)
        | ChainControl::Finalized(block)
        | ChainControl::CanonicalProgress(block)
        | ChainControl::Barrier {
            block: Some(block), ..
        } => assert_canonical_block_identity(asserted_blocks, block, "chain control"),
        ChainControl::Barrier { block: None, .. } => Ok(()),
        ChainControl::Reorg {
            common_ancestor,
            new_tip,
            ..
        } => {
            asserted_blocks.retain(|number, _| *number <= common_ancestor.number);
            assert_canonical_block_identity(
                asserted_blocks,
                common_ancestor,
                "reorg common ancestor",
            )?;
            assert_canonical_block_identity(asserted_blocks, new_tip, "reorg new tip")
        }
    }
}

fn assert_canonical_block_identity(
    asserted_blocks: &mut HashMap<u64, BlockRef>,
    block: &BlockRef,
    label: &str,
) -> Result<(), ReactiveError> {
    for asserted in asserted_blocks.values() {
        if asserted.hash == block.hash && asserted.number != block.number {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "{label} hash {:?} is already asserted at height {}, not {}",
                    block.hash, asserted.number, block.number
                ),
            });
        }
        if block
            .parent_hash
            .is_some_and(|parent| parent == asserted.hash)
            && asserted.number.checked_add(1) != Some(block.number)
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "{label} block {}:{:?} names hash {:?} from known height {} as a non-adjacent parent",
                    block.number, block.hash, asserted.hash, asserted.number
                ),
            });
        }
        if asserted
            .parent_hash
            .is_some_and(|parent| parent == block.hash)
            && block.number.checked_add(1) != Some(asserted.number)
        {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "block {}:{:?} asserted earlier names {label} hash {:?} from non-adjacent height {} as its parent",
                    asserted.number, asserted.hash, block.hash, block.number
                ),
            });
        }
    }
    if let Some(known) = asserted_blocks.get_mut(&block.number) {
        if !optional_block_refs_are_compatible(Some(known), Some(block)) {
            return Err(ReactiveError::InvalidChainControl {
                message: format!(
                    "{label} block {}:{:?} conflicts with block identity {:?} asserted earlier in the batch",
                    block.number, block.hash, known
                ),
            });
        }
        enrich_block_ref(known, block);
    } else {
        asserted_blocks.insert(block.number, *block);
    }
    Ok(())
}

fn set_or_enrich_block_ref(current: &mut Option<BlockRef>, incoming: &BlockRef) {
    match current {
        Some(current) if current.number == incoming.number && current.hash == incoming.hash => {
            enrich_block_ref(current, incoming);
        }
        _ => *current = Some(*incoming),
    }
}

fn advance_or_enrich_coverage(current: &mut Option<BlockRef>, incoming: &BlockRef) {
    match current {
        Some(current) if current.number == incoming.number && current.hash == incoming.hash => {
            enrich_block_ref(current, incoming);
        }
        Some(current) if current.number >= incoming.number => {}
        _ => *current = Some(*incoming),
    }
}

fn validate_adjacent_finality(
    finalized: Option<&BlockRef>,
    safe: Option<&BlockRef>,
) -> Result<(), ReactiveError> {
    let Some((finalized, safe)) = finalized.zip(safe) else {
        return Ok(());
    };
    if finalized.number.checked_add(1) == Some(safe.number)
        && safe.parent_hash != Some(finalized.hash)
    {
        return Err(ReactiveError::InvalidChainControl {
            message: "adjacent safe head does not descend from finalized head".into(),
        });
    }
    Ok(())
}

/// Fold every address a [`StateDiff`] references — genuine changes
/// (`slots`/`accounts`/`purged`) and cold-skipped attempts (`skipped*`) alike —
/// into `into`. Used by the per-block root gate to accumulate the batch's
/// decoder-touched address set: an account a decoder wrote (or tried to write) is
/// "covered," so a subsequent root move for it is not a coverage gap.
fn collect_diff_addresses(diff: &StateDiff, into: &mut HashSet<Address>) {
    into.extend(diff.slots.iter().map(|change| change.address));
    into.extend(diff.accounts.iter().map(|change| change.address));
    into.extend(diff.purged.iter().map(|purge| purge.address));
    into.extend(diff.skipped.iter().map(|skipped| skipped.address));
    into.extend(diff.skipped_balances.iter().map(|skipped| skipped.address));
    into.extend(diff.skipped_masks.iter().map(|skipped| skipped.address));
    into.extend(diff.skipped_accounts.iter().map(|skipped| skipped.address));
}

/// Build the [`ResyncReason::RootMoved`] account resync the root gate schedules
/// for an uncovered move. Re-reads `address`'s `fields` at `block` through the
/// existing account-resync path (Wave 2). The id is derived from the address and
/// block so a repeated move on the same account/block coalesces deterministically.
fn root_moved_account_resync(
    address: Address,
    block: u64,
    fields: AccountFieldMask,
) -> ResyncRequest {
    ResyncRequest {
        id: ResyncId::new(format!("root-moved:{address:#x}:{block}")),
        reason: ResyncReason::RootMoved,
        block: ResyncBlock::Number(block),
        targets: vec![ResyncTarget::Account { address, fields }],
        priority: ResyncPriority::Normal,
    }
}

fn batch_preconfirmation<N: Network>(
    batch: &ReactiveInputBatch<N>,
) -> Result<Option<FlashblockRef>, ReactiveError> {
    let mut flashblock: Option<FlashblockRef> = None;
    let mut has_non_preconfirmed = false;
    for (index, record) in batch.records().iter().enumerate() {
        match &record.context.chain_status {
            ChainStatus::Preconfirmed {
                flashblock: current,
            } => {
                if batch.record_delivery_scope(index) != Some(DeliveryScope::Preconfirmed) {
                    return Err(ReactiveError::InvalidInputRecord {
                        message: "pre-confirmed input requires pre-confirmed delivery scope".into(),
                    });
                }
                if flashblock.as_ref().is_some_and(|known| known != current) {
                    return Err(ReactiveError::InvalidInputRecord {
                        message: "one batch cannot mix distinct Flashblock snapshots".into(),
                    });
                }
                flashblock.get_or_insert_with(|| current.clone());
            }
            _ => has_non_preconfirmed = true,
        }
    }
    if flashblock.is_some() && (has_non_preconfirmed || !batch.chain_controls().is_empty()) {
        return Err(ReactiveError::InvalidInputRecord {
            message: "pre-confirmed delivery cannot mix canonical inputs or chain controls".into(),
        });
    }
    Ok(flashblock)
}

fn canonical_record_block<N: Network>(record: &ReactiveInputRecord<N>) -> Option<&BlockRef> {
    if matches!(&record.input, ReactiveInput::Log(log) if log.removed) {
        return None;
    }
    if is_canonical_status(&record.context.chain_status) {
        return context_block_ref(&record.context);
    }
    None
}

fn resolve_record_block_payload_metadata<N: Network>(
    record: &ReactiveInputRecord<N>,
    mut block: BlockRef,
) -> Result<BlockRef, ReactiveError> {
    let ReactiveInput::Log(log) = &record.input else {
        return Ok(block);
    };
    if log.block_number != Some(block.number) || log.block_hash != Some(block.hash) {
        return Err(ReactiveError::InvalidInputRecord {
            message: "log payload and canonical context carry different block identities".into(),
        });
    }
    if let Some(timestamp) = log.block_timestamp {
        if block.timestamp.is_some_and(|known| known != timestamp) {
            return Err(ReactiveError::InvalidInputRecord {
                message: "log payload and canonical context carry different block timestamps"
                    .into(),
            });
        }
        block.timestamp = Some(timestamp);
    }
    Ok(block)
}

fn validate_input_record<N: Network>(record: &ReactiveInputRecord<N>) -> Result<(), ReactiveError> {
    let invalid = |message: String| ReactiveError::InvalidInputRecord { message };
    if let ChainStatus::Preconfirmed { flashblock } = &record.context.chain_status
        && record.context.block != Some(flashblock.block_ref())
    {
        return Err(invalid(
            "pre-confirmed status and context carry different partial block identities".into(),
        ));
    }
    let status_block = match &record.context.chain_status {
        ChainStatus::Included { block, .. }
        | ChainStatus::Safe { block }
        | ChainStatus::Finalized { block }
        | ChainStatus::Reorged {
            dropped_from: block,
        } => Some(block),
        ChainStatus::Preconfirmed { .. } => record.context.block.as_ref(),
        ChainStatus::Pending => None,
    };
    match (status_block, record.context.block.as_ref()) {
        (Some(status), Some(context)) if status == context => {}
        (Some(_), Some(_)) => {
            return Err(invalid(
                "chain status and context carry different block identities".into(),
            ));
        }
        (Some(_), None) => {
            return Err(invalid(
                "included or reorged input is missing its context block".into(),
            ));
        }
        (None, Some(_)) => {
            return Err(invalid(
                "pending input cannot carry a canonical context block".into(),
            ));
        }
        (None, None) => {}
    }

    match &record.input {
        ReactiveInput::Log(log) => {
            let Some(block) = status_block else {
                return Err(invalid(
                    "log input must carry an included or reorged block identity".into(),
                ));
            };
            if log.removed && !matches!(record.context.chain_status, ChainStatus::Reorged { .. }) {
                return Err(invalid(
                    "removed log must carry reorged chain status".into(),
                ));
            }
            let block_number = log
                .block_number
                .ok_or_else(|| invalid("log is missing its block number".into()))?;
            let block_hash = log
                .block_hash
                .ok_or_else(|| invalid("log is missing its block hash".into()))?;
            log.transaction_hash
                .ok_or_else(|| invalid("log is missing its transaction hash".into()))?;
            let transaction_index = log
                .transaction_index
                .ok_or_else(|| invalid("log is missing its transaction index".into()))?;
            let log_index = log
                .log_index
                .ok_or_else(|| invalid("log is missing its log index".into()))?;
            if block_number != block.number
                || block_hash != block.hash
                || !optional_metadata_compatible(
                    log.block_timestamp.as_ref(),
                    block.timestamp.as_ref(),
                )
            {
                return Err(invalid(
                    "log payload and context carry different block identities".into(),
                ));
            }
            if record.context.transaction_index != Some(transaction_index)
                || record.context.log_index != Some(log_index)
            {
                return Err(invalid(
                    "log payload and context carry different transaction/log positions".into(),
                ));
            }
        }
        ReactiveInput::BlockHeader(header) => {
            if let Some(block) = status_block {
                if header.number() != block.number
                    || header.hash() != block.hash
                    || Some(header.parent_hash()) != block.parent_hash
                    || Some(header.timestamp()) != block.timestamp
                {
                    return Err(invalid(
                        "block header payload and context carry different block identities".into(),
                    ));
                }
            } else if !matches!(record.context.chain_status, ChainStatus::Pending) {
                return Err(invalid("block header has an unsupported lifecycle".into()));
            }
            if record.context.transaction_index.is_some() || record.context.log_index.is_some() {
                return Err(invalid(
                    "block header context cannot carry transaction/log positions".into(),
                ));
            }
        }
        ReactiveInput::FullBlock(block_response) => {
            let header = block_response.header();
            if let Some(block) = status_block {
                if header.number() != block.number
                    || header.hash() != block.hash
                    || Some(header.parent_hash()) != block.parent_hash
                    || Some(header.timestamp()) != block.timestamp
                {
                    return Err(invalid(
                        "full-block payload and context carry different block identities".into(),
                    ));
                }
            } else if !matches!(record.context.chain_status, ChainStatus::Pending) {
                return Err(invalid("full block has an unsupported lifecycle".into()));
            }
            if record.context.transaction_index.is_some() || record.context.log_index.is_some() {
                return Err(invalid(
                    "full-block context cannot carry transaction/log positions".into(),
                ));
            }
            if let Some(transactions) = block_response.transactions().as_transactions() {
                for (index, transaction) in transactions.iter().enumerate() {
                    if transaction
                        .block_hash()
                        .is_some_and(|hash| hash != header.hash())
                        || transaction
                            .block_number()
                            .is_some_and(|number| number != header.number())
                        || transaction
                            .transaction_index()
                            .is_some_and(|position| position != index as u64)
                    {
                        return Err(invalid(format!(
                            "full-block transaction {index} carries contradictory inclusion metadata"
                        )));
                    }
                    if transaction
                        .chain_id()
                        .zip(record.context.chain_id)
                        .is_some_and(|(transaction, context)| transaction != context)
                    {
                        return Err(invalid(format!(
                            "full-block transaction {index} carries a chain id conflicting with its context"
                        )));
                    }
                }
            }
        }
        ReactiveInput::PendingTxHash(_) => {
            if !matches!(record.context.chain_status, ChainStatus::Pending) {
                return Err(invalid(
                    "pending transaction input must carry pending chain status".into(),
                ));
            }
            if record.context.transaction_index.is_some() || record.context.log_index.is_some() {
                return Err(invalid(
                    "pending transaction context cannot carry canonical positions".into(),
                ));
            }
        }
        ReactiveInput::PendingTx(transaction) => {
            if !matches!(record.context.chain_status, ChainStatus::Pending) {
                return Err(invalid(
                    "pending transaction input must carry pending chain status".into(),
                ));
            }
            if record.context.transaction_index.is_some() || record.context.log_index.is_some() {
                return Err(invalid(
                    "pending transaction context cannot carry canonical positions".into(),
                ));
            }
            if transaction.block_hash().is_some()
                || transaction.block_number().is_some()
                || transaction.transaction_index().is_some()
            {
                return Err(invalid(
                    "hydrated pending transaction cannot carry inclusion metadata".into(),
                ));
            }
            if transaction
                .chain_id()
                .zip(record.context.chain_id)
                .is_some_and(|(transaction, context)| transaction != context)
            {
                return Err(invalid(
                    "pending transaction carries a chain id conflicting with its context".into(),
                ));
            }
        }
    }
    Ok(())
}

/// Best-effort per-block env refresh (Phase-8 step 2).
///
/// For a canonical record carrying a full header — a
/// [`ReactiveInput::BlockHeader`] or [`ReactiveInput::FullBlock`] — refresh the
/// cache's block env from that header via [`EvmCache::advance_block`]. Returns
/// `Some(result)` when a header was present (so the caller can surface a strict
/// validation error), and `None` for pending/reorged records or non-header
/// inputs, which must never drive a canonical env refresh.
fn advance_block_for_canonical_record<N: Network>(
    cache: &mut EvmCache,
    record: &ReactiveInputRecord<N>,
) -> Option<Result<(), BlockContextError>> {
    if !is_canonical_status(&record.context.chain_status) {
        return None;
    }
    match &record.input {
        ReactiveInput::BlockHeader(header) => Some(cache.advance_block(header)),
        ReactiveInput::FullBlock(block) => Some(cache.advance_block(block.header())),
        _ => None,
    }
}

fn context_block_ref(ctx: &ReactiveContext) -> Option<&BlockRef> {
    match &ctx.chain_status {
        ChainStatus::Included { block, .. }
        | ChainStatus::Safe { block }
        | ChainStatus::Finalized { block } => Some(block),
        ChainStatus::Reorged { dropped_from } => Some(dropped_from),
        ChainStatus::Preconfirmed { .. } => ctx.block.as_ref(),
        ChainStatus::Pending => ctx.block.as_ref(),
    }
}

fn reorg_signal_block<N: Network>(
    record: &ReactiveInputRecord<N>,
) -> Option<(BlockRef, ReorgReason)> {
    if matches!(&record.input, ReactiveInput::Log(log) if log.removed) {
        return block_ref_from_record(record).map(|block| (block, ReorgReason::RemovedLog));
    }

    if let ChainStatus::Reorged { dropped_from } = &record.context.chain_status {
        return Some((*dropped_from, ReorgReason::ReorgedInput));
    }

    None
}

fn block_ref_from_record<N: Network>(record: &ReactiveInputRecord<N>) -> Option<BlockRef> {
    context_block_ref(&record.context)
        .cloned()
        .or_else(|| match &record.input {
            ReactiveInput::Log(log) => Some(BlockRef {
                number: log.block_number?,
                hash: log.block_hash?,
                parent_hash: None,
                timestamp: log.block_timestamp,
            }),
            ReactiveInput::BlockHeader(header) => Some(BlockRef {
                number: header.number(),
                hash: header.hash(),
                parent_hash: Some(header.parent_hash()),
                timestamp: Some(header.timestamp()),
            }),
            ReactiveInput::FullBlock(block) => {
                let header = block.header();
                Some(BlockRef {
                    number: header.number(),
                    hash: header.hash(),
                    parent_hash: Some(header.parent_hash()),
                    timestamp: Some(header.timestamp()),
                })
            }
            ReactiveInput::PendingTxHash(_) | ReactiveInput::PendingTx(_) => None,
        })
}

fn remove_canceled_resyncs_from_batch(
    resyncs: &mut Vec<ResyncRequest>,
    canceled: &[ResyncRequest],
) {
    if canceled.is_empty() {
        return;
    }
    let canceled_ids: HashSet<_> = canceled.iter().map(|request| request.id.clone()).collect();
    resyncs.retain(|request| !canceled_ids.contains(&request.id));
}

fn resync_target_address(target: &ResyncTarget) -> Address {
    match target {
        ResyncTarget::StorageSlot { address, .. }
        | ResyncTarget::StorageSlots { address, .. }
        | ResyncTarget::Account { address, .. } => *address,
    }
}

fn resync_request_targets_dropped_block(
    request: &ResyncRequest,
    dropped_blocks: &[BlockRef],
) -> bool {
    let ResyncBlock::Hash { number, hash, .. } = &request.block else {
        return false;
    };
    dropped_blocks
        .iter()
        .any(|block| block.hash == *hash && block.number == *number)
}

fn single_hash_pinned_resync_block(report: &ResyncReport) -> Option<BlockRef> {
    let first = report.requested.first()?.block.clone();
    if !report
        .requested
        .iter()
        .all(|request| request.block == first)
    {
        return None;
    }

    let ResyncBlock::Hash { number, hash, .. } = first else {
        return None;
    };

    Some(BlockRef {
        number,
        hash,
        parent_hash: None,
        timestamp: None,
    })
}

fn purge_scopes_for_dropped_journals<N: Network>(
    dropped: &[BlockJournal<N>],
) -> Vec<(Address, PurgeScope)> {
    let mut scopes: Vec<(Address, PurgeScope)> = Vec::new();
    for entry in dropped.iter().rev() {
        for diff in entry.rollback_diffs.iter().rev() {
            merge_purge_scopes_for_diff(&mut scopes, diff);
        }
    }
    scopes
}

fn rollback_updates_for_dropped_journals<N: Network>(
    dropped: &[BlockJournal<N>],
    purge_scopes: &[(Address, PurgeScope)],
) -> Vec<StateUpdate> {
    let purge_addresses: HashSet<_> = purge_scopes
        .iter()
        .map(|(address, _scope)| *address)
        .collect();
    let mut updates = Vec::new();
    for entry in dropped.iter().rev() {
        for diff in entry.rollback_diffs.iter().rev() {
            push_rollback_updates_for_diff(&mut updates, diff, &purge_addresses);
        }
    }
    updates
}

fn merge_purge_scopes_for_diff(scopes: &mut Vec<(Address, PurgeScope)>, diff: &StateDiff) {
    for change in &diff.accounts {
        merge_purge_scope(scopes, change.address, PurgeScope::Account);
    }
    for record in &diff.purged {
        merge_purge_scope(scopes, record.address, record.scope.clone());
    }
}

fn push_rollback_updates_for_diff(
    updates: &mut Vec<StateUpdate>,
    diff: &StateDiff,
    purge_addresses: &HashSet<Address>,
) {
    for change in diff.slots.iter().rev() {
        if purge_addresses.contains(&change.address) {
            continue;
        }
        updates.push(StateUpdate::slot(change.address, change.slot, change.old));
    }
}

fn merge_purge_scope(scopes: &mut Vec<(Address, PurgeScope)>, address: Address, scope: PurgeScope) {
    if let Some((_existing_address, existing_scope)) = scopes
        .iter_mut()
        .find(|(existing_address, _scope)| *existing_address == address)
    {
        *existing_scope = merged_purge_scope(existing_scope.clone(), scope);
    } else {
        scopes.push((address, scope));
    }
}

fn merged_purge_scope(left: PurgeScope, right: PurgeScope) -> PurgeScope {
    match (left, right) {
        (PurgeScope::Account, _) | (_, PurgeScope::Account) => PurgeScope::Account,
        (PurgeScope::AllStorage, _) | (_, PurgeScope::AllStorage) => PurgeScope::AllStorage,
        (PurgeScope::Slots(mut left), PurgeScope::Slots(right)) => {
            for slot in right {
                if !left.contains(&slot) {
                    left.push(slot);
                }
            }
            PurgeScope::Slots(left)
        }
    }
}

#[derive(Clone, Debug)]
struct StorageFetchSlot {
    address: Address,
    slot: U256,
    origins: Vec<StorageFetchOrigin>,
}

#[derive(Clone, Debug)]
struct StorageFetchOrigin {
    request_id: ResyncId,
    target: ResyncTarget,
}

#[derive(Clone, Debug)]
struct StorageFetchGroup {
    block: ResyncBlock,
    slots: Vec<StorageFetchSlot>,
    seen: HashSet<(Address, U256)>,
}

/// One account-target resync collected during request scanning, resolved through
/// the account proof fetcher after storage groups are processed.
#[derive(Clone, Debug)]
struct AccountResyncTarget {
    request_id: ResyncId,
    block: ResyncBlock,
    address: Address,
    fields: AccountFieldMask,
}

fn resolve_trace_resyncs(
    cache: &EvmCache,
    storage_groups: &mut Vec<StorageFetchGroup>,
    account_targets: &mut Vec<AccountResyncTarget>,
    state_updates: &mut Vec<StateUpdate>,
) {
    let Some(fetcher) = cache.block_state_diff_fetcher().cloned() else {
        return;
    };

    let mut blocks = Vec::new();
    let mut seen = HashSet::new();
    for block in storage_groups
        .iter()
        .map(|group| group.block.clone())
        .chain(account_targets.iter().map(|target| target.block.clone()))
    {
        if seen.insert(block.clone()) {
            blocks.push(block);
        }
    }

    let mut traces = HashMap::new();
    for block in blocks {
        match (fetcher)(resync_block_to_block_id(&block)) {
            Ok(diff) => {
                traces.insert(block, diff);
            }
            Err(error) => {
                tracing::debug!(
                    block = ?block,
                    error = %error,
                    "block trace resync source failed; falling back to point resync"
                );
            }
        }
    }

    for group in storage_groups.iter_mut() {
        let Some(trace) = traces.get(&group.block) else {
            continue;
        };
        group.slots.retain(|slot| {
            if let Some(value) = trace_storage_value(trace, slot.address, slot.slot) {
                state_updates.push(StateUpdate::slot(slot.address, slot.slot, value));
                return false;
            }
            cache
                .cached_storage_value(slot.address, slot.slot)
                .is_none()
        });
        group.seen = group
            .slots
            .iter()
            .map(|slot| (slot.address, slot.slot))
            .collect();
    }
    storage_groups.retain(|group| !group.slots.is_empty());

    let mut unresolved_accounts = Vec::new();
    for mut account in account_targets.drain(..) {
        let Some(trace) = traces.get(&account.block) else {
            unresolved_accounts.push(account);
            continue;
        };
        let Some(trace_account) = trace
            .accounts
            .iter()
            .find(|diff| diff.address == account.address)
        else {
            unresolved_accounts.push(account);
            continue;
        };

        let mut patch = AccountPatch::default();
        let mut unresolved = AccountFieldMask::default();
        if account.fields.balance {
            if let Some(balance) = trace_account.balance {
                patch = patch.balance(balance);
            } else {
                unresolved.balance = true;
            }
        }
        if account.fields.nonce {
            if let Some(nonce) = trace_account.nonce {
                patch = patch.nonce(nonce);
            } else {
                unresolved.nonce = true;
            }
        }
        if account.fields.code {
            if let Some(code) = &trace_account.code {
                patch = patch.code(code.clone());
            } else {
                unresolved.code = true;
            }
        }

        if patch.balance.is_some() || patch.nonce.is_some() || patch.code.is_some() {
            state_updates.push(StateUpdate::account_upsert(account.address, patch));
        }
        if !account_field_mask_empty(unresolved) {
            account.fields = unresolved;
            unresolved_accounts.push(account);
        }
    }
    *account_targets = unresolved_accounts;
}

fn trace_storage_value(trace: &BlockStateDiff, address: Address, slot: U256) -> Option<U256> {
    trace
        .accounts
        .iter()
        .find(|account| account.address == address)
        .and_then(|account| {
            account
                .storage
                .iter()
                .find(|entry| entry.slot == slot)
                .map(|entry| entry.value)
        })
}

fn account_field_mask_empty(mask: AccountFieldMask) -> bool {
    !mask.balance && !mask.nonce && !mask.code
}

fn execute_resync_requests(cache: &mut EvmCache, requests: &[ResyncRequest]) -> ResyncReport {
    let mut failed = Vec::new();
    let mut storage_groups: Vec<StorageFetchGroup> = Vec::new();
    let mut account_targets: Vec<AccountResyncTarget> = Vec::new();

    for request in requests {
        for target in &request.targets {
            match target {
                ResyncTarget::StorageSlot { address, slot } => {
                    push_storage_resync_slot(
                        &mut storage_groups,
                        &request.id,
                        &request.block,
                        *address,
                        *slot,
                    );
                }
                ResyncTarget::StorageSlots { address, slots } => {
                    for slot in slots {
                        push_storage_resync_slot(
                            &mut storage_groups,
                            &request.id,
                            &request.block,
                            *address,
                            *slot,
                        );
                    }
                }
                ResyncTarget::Account { address, fields } => {
                    account_targets.push(AccountResyncTarget {
                        request_id: request.id.clone(),
                        block: request.block.clone(),
                        address: *address,
                        fields: *fields,
                    });
                }
            }
        }
    }

    let mut state_updates = Vec::new();
    resolve_trace_resyncs(
        cache,
        &mut storage_groups,
        &mut account_targets,
        &mut state_updates,
    );

    if !storage_groups.is_empty() {
        if let Some(fetcher) = cache.storage_batch_fetcher().cloned() {
            for group in storage_groups {
                let block = group.block.clone();
                let fetches: Vec<(Address, U256)> = group
                    .slots
                    .iter()
                    .map(|slot| (slot.address, slot.slot))
                    .collect();
                let results = (fetcher)(fetches, resync_block_to_block_id(&block));
                let mut pending: HashMap<(Address, U256), StorageFetchSlot> = group
                    .slots
                    .iter()
                    .cloned()
                    .map(|slot| ((slot.address, slot.slot), slot))
                    .collect();

                for (address, slot, fetched) in results {
                    let Some(requested_slot) = pending.remove(&(address, slot)) else {
                        continue;
                    };
                    match fetched {
                        Ok(value) => state_updates.push(StateUpdate::slot(address, slot, value)),
                        Err(error) => {
                            let message = error.to_string();
                            push_resync_failures(
                                &mut failed,
                                &block,
                                requested_slot.origins,
                                ResyncFailureKind::StorageFetchFailed,
                                message,
                            );
                        }
                    }
                }

                for requested_slot in group.slots {
                    if pending
                        .remove(&(requested_slot.address, requested_slot.slot))
                        .is_some()
                    {
                        push_resync_failures(
                            &mut failed,
                            &block,
                            requested_slot.origins,
                            ResyncFailureKind::StorageFetchOmitted,
                            "storage batch fetcher did not return a value for slot".to_string(),
                        );
                    }
                }
            }
        } else {
            for group in storage_groups {
                let block = group.block.clone();
                for slot in group.slots {
                    push_resync_failures(
                        &mut failed,
                        &block,
                        slot.origins,
                        ResyncFailureKind::MissingStorageFetcher,
                        "storage resync requires a storage batch fetcher".to_string(),
                    );
                }
            }
        }
    }

    if !account_targets.is_empty() {
        if let Some(fetcher) = cache.account_proof_fetcher().cloned() {
            // ONE seam invocation per distinct resync block (targets may pin
            // different blocks): eth_getProof is single-address at the RPC
            // level, so batching the addresses lets the fetcher fan the
            // requests out concurrently instead of paying one round trip per
            // account. Root-only probes: account fields need no storage keys.
            let mut groups: Vec<(BlockId, Vec<_>)> = Vec::new();
            for account in account_targets {
                let block_id = resync_block_to_block_id(&account.block);
                match groups
                    .iter_mut()
                    .find(|(group_block, _)| *group_block == block_id)
                {
                    Some((_, group)) => group.push(account),
                    None => groups.push((block_id, vec![account])),
                }
            }
            for (block_id, group) in groups {
                let probes: HashMap<Address, StorageFetchResult<AccountProof>> = (fetcher)(
                    group
                        .iter()
                        .map(|account| (account.address, vec![]))
                        .collect(),
                    block_id,
                )
                .into_iter()
                .collect();
                for account in group {
                    // `get` + clone rather than `remove`: two targets for the
                    // same address in one group must both resolve from the
                    // single probe.
                    match probes.get(&account.address).cloned() {
                        Some(Ok(proof)) => {
                            // Build an authoritative account update from the requested
                            // field mask. Use the MATERIALIZING `account_upsert` so a
                            // resync applies even to a cold account (a partial `Account`
                            // patch on a cold address is silently skipped).
                            let mut patch = AccountPatch::default();
                            if account.fields.balance {
                                patch = patch.balance(proof.balance);
                            }
                            if account.fields.nonce {
                                patch = patch.nonce(proof.nonce);
                            }
                            // Note: `AccountProof` carries `code_hash`, not code bytes;
                            // the `eth_getProof` seam cannot supply runtime code, so a
                            // code-field resync is a no-op here (code freshness is
                            // handled by a later wave). We still materialize the account
                            // so requested balance/nonce fields take effect.
                            state_updates.push(StateUpdate::account_upsert(account.address, patch));
                        }
                        Some(Err(error)) => {
                            failed.push(ResyncFailure {
                                request_id: account.request_id,
                                block: account.block,
                                target: ResyncTarget::Account {
                                    address: account.address,
                                    fields: account.fields,
                                },
                                kind: ResyncFailureKind::AccountFetchFailed,
                                message: error.to_string(),
                            });
                        }
                        None => {
                            failed.push(ResyncFailure {
                                request_id: account.request_id,
                                block: account.block,
                                target: ResyncTarget::Account {
                                    address: account.address,
                                    fields: account.fields,
                                },
                                kind: ResyncFailureKind::AccountFetchOmitted,
                                message:
                                    "account proof fetcher did not return a result for address"
                                        .to_string(),
                            });
                        }
                    }
                }
            }
        } else {
            for account in account_targets {
                failed.push(ResyncFailure {
                    request_id: account.request_id,
                    block: account.block,
                    target: ResyncTarget::Account {
                        address: account.address,
                        fields: account.fields,
                    },
                    kind: ResyncFailureKind::MissingAccountFetcher,
                    message: "account resync requires an account proof fetcher".to_string(),
                });
            }
        }
    }

    let diff = if state_updates.is_empty() {
        StateDiff::default()
    } else {
        cache.apply_updates(&state_updates)
    };

    ResyncReport {
        requested: requests.to_vec(),
        state_updates,
        diff,
        failed,
    }
}

fn push_resync_failures(
    failed: &mut Vec<ResyncFailure>,
    block: &ResyncBlock,
    origins: Vec<StorageFetchOrigin>,
    kind: ResyncFailureKind,
    message: String,
) {
    for origin in origins {
        failed.push(ResyncFailure {
            request_id: origin.request_id,
            block: block.clone(),
            target: origin.target,
            kind,
            message: message.clone(),
        });
    }
}

fn push_storage_resync_slot(
    groups: &mut Vec<StorageFetchGroup>,
    request_id: &ResyncId,
    block: &ResyncBlock,
    address: Address,
    slot: U256,
) {
    let group_index = if let Some(index) = groups.iter().position(|group| group.block == *block) {
        index
    } else {
        groups.push(StorageFetchGroup {
            block: block.clone(),
            slots: Vec::new(),
            seen: HashSet::new(),
        });
        groups.len() - 1
    };

    let group = &mut groups[group_index];
    let origin = StorageFetchOrigin {
        request_id: request_id.clone(),
        target: ResyncTarget::StorageSlot { address, slot },
    };
    if group.seen.insert((address, slot)) {
        group.slots.push(StorageFetchSlot {
            address,
            slot,
            origins: vec![origin],
        });
    } else if let Some(existing) = group
        .slots
        .iter_mut()
        .find(|existing| existing.address == address && existing.slot == slot)
    {
        existing.origins.push(origin);
    }
}

fn resync_block_to_block_id(block: &ResyncBlock) -> BlockId {
    match block {
        ResyncBlock::Latest => BlockId::latest(),
        ResyncBlock::Pending => BlockId::pending(),
        ResyncBlock::Safe => BlockId::safe(),
        ResyncBlock::Finalized => BlockId::finalized(),
        ResyncBlock::Number(number) => BlockId::number(*number),
        ResyncBlock::Hash {
            number: _,
            hash,
            require_canonical,
        } => BlockId::from((*hash, Some(*require_canonical))),
    }
}

impl<N: Network> RegisteredHandler<N> {
    fn matches(&self, input: &ReactiveInput<N>) -> bool {
        self.interests
            .iter()
            .any(|interest| interest_matches(interest, input))
    }

    fn route_log(&self, log: &Log) -> Option<ReactiveLogRoute> {
        self.interests.iter().find_map(|interest| match interest {
            ReactiveInterest::Logs(interest) if interest.matches(log) => Some(ReactiveLogRoute {
                handler_id: self.id.clone(),
                route_key: interest.route_key(log),
            }),
            ReactiveInterest::Logs(_)
            | ReactiveInterest::Blocks(_)
            | ReactiveInterest::PendingTransactions(_) => None,
        })
    }
}

fn merge_log_subscription_filter(filters: &mut Vec<Filter>, next: &Filter) {
    let mut candidate = next.clone();
    let mut insertion_index = filters.len();
    let mut index = 0;
    while index < filters.len() {
        if filters[index].block_option != candidate.block_option {
            index += 1;
            continue;
        }
        if let Some(merged) = exact_filter_union(&candidate, &filters[index]) {
            candidate = merged;
            insertion_index = insertion_index.min(index);
            filters.remove(index);
            index = 0;
        } else {
            index += 1;
        }
    }
    filters.insert(insertion_index.min(filters.len()), candidate);
}

fn exact_filter_union(left: &Filter, right: &Filter) -> Option<Filter> {
    if filter_subsumes(left, right) {
        return Some(left.clone());
    }
    if filter_subsumes(right, left) {
        return Some(right.clone());
    }
    let differing_dimensions = usize::from(left.address != right.address)
        + left
            .topics
            .iter()
            .zip(right.topics.iter())
            .filter(|(left, right)| left != right)
            .count();
    if differing_dimensions != 1 {
        return None;
    }

    let mut merged = left.clone();
    if merged.address != right.address {
        merge_filter_set(&mut merged.address, &right.address);
    } else {
        for (merged_topic, right_topic) in merged.topics.iter_mut().zip(right.topics.iter()) {
            if merged_topic != right_topic {
                merge_filter_set(merged_topic, right_topic);
                break;
            }
        }
    }
    Some(merged)
}

fn filter_subsumes(left: &Filter, right: &Filter) -> bool {
    filter_set_subsumes(&left.address, &right.address)
        && left
            .topics
            .iter()
            .zip(right.topics.iter())
            .all(|(left, right)| filter_set_subsumes(left, right))
}

fn filter_set_subsumes<T: Eq + Hash>(left: &FilterSet<T>, right: &FilterSet<T>) -> bool {
    left.is_empty()
        || (!right.is_empty()
            && right
                .iter()
                .all(|value| left.iter().any(|known| known == value)))
}

fn merge_filter_set<T: Clone + Eq + Hash>(target: &mut FilterSet<T>, source: &FilterSet<T>) {
    if target.is_empty() {
        return;
    }
    if source.is_empty() {
        *target = FilterSet::default();
        return;
    }
    for value in source.iter() {
        target.insert(value.clone());
    }
}

#[derive(Clone, Debug)]
struct HandlerExecution {
    handler_id: HandlerId,
    quality: StateEffectQuality,
    tags: Vec<ReportTag>,
    state_updates: Vec<StateUpdate>,
    invalidations: Vec<InvalidationRequest>,
    resyncs: Vec<ResyncRequest>,
    speculative: Vec<SpeculativeRequest>,
    hook_signals: Vec<HookSignal>,
}

impl HandlerExecution {
    fn from_outcome(
        handler_id: HandlerId,
        input_ref: InputRef,
        outcome: HandlerOutcome,
        preconfirmed: bool,
    ) -> Self {
        let mut state_updates = Vec::new();
        let mut invalidations = Vec::new();
        let mut resyncs = Vec::new();
        let mut speculative = Vec::new();
        let mut hook_signals = Vec::new();

        for effect in outcome.effects {
            match effect {
                ReactiveEffect::StateUpdate(update) => state_updates.push(update),
                ReactiveEffect::Invalidate(invalidation) => {
                    state_updates.push(StateUpdate::purge(
                        invalidation.address,
                        invalidation.scope.clone(),
                    ));
                    invalidations.push(invalidation);
                }
                ReactiveEffect::Resync(mut request) => {
                    if preconfirmed {
                        request.block = ResyncBlock::Pending;
                    }
                    resyncs.push(request);
                }
                ReactiveEffect::Hook(signal) => hook_signals.push(signal),
                ReactiveEffect::Speculative(mut request) => {
                    request.input_ref = input_ref;
                    speculative.push(request);
                }
            }
        }

        Self {
            handler_id,
            quality: outcome.quality,
            tags: outcome.tags,
            state_updates,
            invalidations,
            resyncs,
            speculative,
            hook_signals,
        }
    }
}

fn dedupe_records<N: Network>(
    records: Vec<ReactiveInputRecord<N>>,
) -> Result<Vec<ReactiveInputRecord<N>>, ReactiveError> {
    let mut positions = HashMap::<ReactiveInputIdentity, usize>::new();
    let mut deduped = Vec::with_capacity(records.len());
    for record in records {
        let identity = record.validated_identity()?;
        if !record.is_payload_deduplicable() {
            deduped.push(record);
            continue;
        }
        if let Some(index) = positions.get(&identity).copied() {
            let merged = deduped[index].merge_compatible_duplicate(&record)?;
            debug_assert!(merged, "same indexed identity is deduplicable");
        } else {
            positions.insert(identity, deduped.len());
            deduped.push(record);
        }
    }
    Ok(deduped)
}

fn dedupe_scoped_records<N: Network>(
    records: Vec<(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)>,
) -> Result<Vec<(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)>, ReactiveError> {
    let mut positions: HashMap<ReactiveInputIdentity, usize> = HashMap::new();
    let mut deduped: Vec<(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)> =
        Vec::with_capacity(records.len());
    for (record, audience, delivery_scope) in records {
        let identity = record.validated_identity()?;
        if !record.is_payload_deduplicable() {
            deduped.push((record, audience, delivery_scope));
            continue;
        }
        if let Some(index) = positions.get(&identity).copied() {
            let merged = deduped[index].0.merge_compatible_duplicate(&record)?;
            debug_assert!(merged, "same indexed identity is deduplicable");
            merge_delivery_audience(&mut deduped[index].1, audience);
            merge_delivery_scope(&mut deduped[index].2, delivery_scope);
        } else {
            positions.insert(identity, deduped.len());
            deduped.push((record, audience, delivery_scope));
        }
    }
    Ok(deduped)
}

fn merge_delivery_scope(into: &mut DeliveryScope, incoming: DeliveryScope) {
    *into = match (*into, incoming) {
        (DeliveryScope::Canonical, _) | (_, DeliveryScope::Canonical) => DeliveryScope::Canonical,
        (DeliveryScope::CanonicalProgress, _) | (_, DeliveryScope::CanonicalProgress) => {
            DeliveryScope::CanonicalProgress
        }
        (DeliveryScope::Preconfirmed, DeliveryScope::Preconfirmed)
        | (DeliveryScope::Preconfirmed, DeliveryScope::OwnerCatchup)
        | (DeliveryScope::OwnerCatchup, DeliveryScope::Preconfirmed) => DeliveryScope::Preconfirmed,
        (DeliveryScope::OwnerCatchup, DeliveryScope::OwnerCatchup) => DeliveryScope::OwnerCatchup,
    };
}

fn merge_delivery_audience(into: &mut DeliveryAudience, incoming: DeliveryAudience) {
    match (&mut *into, incoming) {
        (DeliveryAudience::All, _) => {}
        (current, DeliveryAudience::All) => *current = DeliveryAudience::All,
        (DeliveryAudience::Owners(current), DeliveryAudience::Owners(incoming)) => {
            for owner in incoming {
                if !current.contains(&owner) {
                    current.push(owner);
                }
            }
        }
        (DeliveryAudience::AllExcept(current), DeliveryAudience::AllExcept(incoming)) => {
            current.retain(|owner| incoming.contains(owner));
        }
        (DeliveryAudience::AllExcept(excluded), DeliveryAudience::Owners(included)) => {
            excluded.retain(|owner| !included.contains(owner));
        }
        (current @ DeliveryAudience::Owners(_), DeliveryAudience::AllExcept(mut excluded)) => {
            let DeliveryAudience::Owners(included) = current else {
                unreachable!("match arm restricts the audience variant")
            };
            excluded.retain(|owner| !included.contains(owner));
            *current = DeliveryAudience::AllExcept(excluded);
        }
    }
}

fn sort_records<N: Network>(records: Vec<ReactiveInputRecord<N>>) -> Vec<ReactiveInputRecord<N>> {
    let mut indexed: Vec<(usize, ReactiveInputRecord<N>)> =
        records.into_iter().enumerate().collect();
    indexed.sort_by_key(|(index, record)| record_sort_key(*index, record));
    indexed.into_iter().map(|(_, record)| record).collect()
}

fn sort_scoped_records<N: Network>(
    records: Vec<(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)>,
) -> Vec<(ReactiveInputRecord<N>, DeliveryAudience, DeliveryScope)> {
    let mut indexed: Vec<_> = records.into_iter().enumerate().collect();
    indexed.sort_by_key(|(index, (record, _, _))| record_sort_key(*index, record));
    indexed
        .into_iter()
        .map(|(_, scoped_record)| scoped_record)
        .collect()
}

fn record_sort_key<N: Network>(index: usize, record: &ReactiveInputRecord<N>) -> RecordSortKey {
    if let Some((block, _)) = reorg_signal_block(record) {
        return RecordSortKey {
            class: 0,
            block_number: block.number,
            record_class: 0,
            transaction_index: record.context.transaction_index.unwrap_or(u64::MAX),
            log_index: record.context.log_index.unwrap_or(u64::MAX),
            original_index: index,
        };
    }
    if is_canonical_status(&record.context.chain_status)
        && let Some(block) = record.context.block.as_ref()
    {
        let (record_class, transaction_index, log_index) = match &record.input {
            ReactiveInput::BlockHeader(_) | ReactiveInput::FullBlock(_) => (0, 0, 0),
            ReactiveInput::Log(log) if !log.removed => (
                1,
                log.transaction_index
                    .or(record.context.transaction_index)
                    .unwrap_or(u64::MAX),
                log.log_index
                    .or(record.context.log_index)
                    .unwrap_or(u64::MAX),
            ),
            ReactiveInput::Log(_)
            | ReactiveInput::PendingTxHash(_)
            | ReactiveInput::PendingTx(_) => (2, u64::MAX, u64::MAX),
        };
        return RecordSortKey {
            class: 1,
            block_number: block.number,
            record_class,
            transaction_index,
            log_index,
            original_index: index,
        };
    }

    RecordSortKey {
        class: 2,
        block_number: 0,
        record_class: 0,
        transaction_index: 0,
        log_index: 0,
        original_index: index,
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
struct RecordSortKey {
    class: u8,
    block_number: u64,
    record_class: u8,
    transaction_index: u64,
    log_index: u64,
    original_index: usize,
}

fn interest_matches<N: Network>(interest: &ReactiveInterest<N>, input: &ReactiveInput<N>) -> bool {
    match (interest, input) {
        (ReactiveInterest::Logs(interest), ReactiveInput::Log(log)) => interest.matches(log),
        (
            ReactiveInterest::Blocks(BlockInterest {
                mode: BlockInterestMode::Header,
            }),
            ReactiveInput::BlockHeader(_),
        ) => true,
        (
            ReactiveInterest::Blocks(BlockInterest {
                mode: BlockInterestMode::FullBlock,
            }),
            ReactiveInput::FullBlock(_),
        ) => true,
        (ReactiveInterest::PendingTransactions(interest), ReactiveInput::PendingTxHash(_)) => {
            interest.matches_hash_only()
        }
        (ReactiveInterest::PendingTransactions(interest), ReactiveInput::PendingTx(tx)) => {
            interest.matches_tx(tx)
        }
        _ => false,
    }
}

fn validate_effects(
    input_ref: InputRef,
    ctx: &ReactiveContext,
    handler_id: &HandlerId,
    effects: &[ReactiveEffect],
) -> Result<(), ReactiveError> {
    let pending = matches!(ctx.chain_status, ChainStatus::Pending)
        || matches!(input_ref, InputRef::PendingTx { .. });
    if !pending {
        return Ok(());
    }

    for effect in effects {
        let effect_kind = match effect {
            ReactiveEffect::StateUpdate(_) => Some("state_update"),
            ReactiveEffect::Invalidate(_) => Some("invalidate"),
            ReactiveEffect::Resync(_) => Some("resync"),
            ReactiveEffect::Hook(_) | ReactiveEffect::Speculative(_) => None,
        };
        if let Some(effect_kind) = effect_kind {
            return Err(ReactiveError::InvalidPendingEffect {
                input_ref: Box::new(input_ref),
                handler_id: handler_id.clone(),
                effect_kind,
            });
        }
    }
    Ok(())
}

fn detect_conflicts(
    input_ref: InputRef,
    executions: &[HandlerExecution],
) -> Result<(), ReactiveError> {
    let mut writes: HashMap<EffectTarget, (AbsoluteValue, HandlerId)> = HashMap::new();
    for execution in executions {
        for update in &execution.state_updates {
            for (target, value) in absolute_writes(update) {
                if let Some((previous_value, previous_handler)) = writes.get(&target) {
                    if previous_value != &value {
                        return Err(ReactiveError::ConflictingEffects {
                            input_ref: Box::new(input_ref),
                            target: Box::new(target),
                            first: previous_handler.clone(),
                            second: execution.handler_id.clone(),
                        });
                    }
                } else {
                    writes.insert(target, (value, execution.handler_id.clone()));
                }
            }
        }
    }
    Ok(())
}

fn absolute_writes(update: &StateUpdate) -> Vec<(EffectTarget, AbsoluteValue)> {
    match update {
        StateUpdate::Slot {
            address,
            slot,
            value,
        } => vec![(
            EffectTarget::StorageSlot {
                address: *address,
                slot: *slot,
            },
            AbsoluteValue::U256(*value),
        )],
        StateUpdate::SlotMasked {
            address,
            slot,
            mask,
            value,
        } => vec![(
            EffectTarget::MaskedStorageSlot {
                address: *address,
                slot: *slot,
                mask: *mask,
            },
            AbsoluteValue::U256(*value),
        )],
        StateUpdate::Account { address, patch } | StateUpdate::AccountUpsert { address, patch } => {
            account_patch_writes(*address, patch)
        }
        StateUpdate::SlotDelta { .. }
        | StateUpdate::BalanceDelta { .. }
        | StateUpdate::Purge { .. } => Vec::new(),
    }
}

fn account_patch_writes(
    address: Address,
    patch: &AccountPatch,
) -> Vec<(EffectTarget, AbsoluteValue)> {
    let mut writes = Vec::new();
    if let Some(balance) = patch.balance {
        writes.push((
            EffectTarget::AccountBalance { address },
            AbsoluteValue::U256(balance),
        ));
    }
    if let Some(nonce) = patch.nonce {
        writes.push((
            EffectTarget::AccountNonce { address },
            AbsoluteValue::U64(nonce),
        ));
    }
    if let Some(code) = &patch.code {
        writes.push((
            EffectTarget::AccountCode { address },
            AbsoluteValue::Bytes(code.clone()),
        ));
    }
    writes
}

fn input_ref<N: Network>(input: &ReactiveInput<N>, ctx: &ReactiveContext) -> InputRef {
    match input {
        ReactiveInput::Log(log) => InputRef::Log {
            chain_id: ctx.chain_id,
            block_hash: log
                .block_hash
                .or(ctx.block.as_ref().map(|block| block.hash))
                .unwrap_or_default(),
            transaction_hash: log.transaction_hash.unwrap_or_default(),
            log_index: log.log_index.or(ctx.log_index).unwrap_or_default(),
        },
        ReactiveInput::PendingTxHash(hash) => InputRef::PendingTx {
            chain_id: ctx.chain_id,
            hash: *hash,
        },
        ReactiveInput::PendingTx(tx) => InputRef::PendingTx {
            chain_id: ctx.chain_id,
            hash: tx.tx_hash(),
        },
        ReactiveInput::BlockHeader(header) => InputRef::Block {
            chain_id: ctx.chain_id,
            hash: header.hash(),
            number: header.number(),
        },
        ReactiveInput::FullBlock(block) => {
            let header = block.header();
            InputRef::Block {
                chain_id: ctx.chain_id,
                hash: header.hash(),
                number: header.number(),
            }
        }
    }
}

fn is_canonical_status(status: &ChainStatus) -> bool {
    matches!(
        status,
        ChainStatus::Included { .. } | ChainStatus::Safe { .. } | ChainStatus::Finalized { .. }
    )
}

/// Adapter that wraps a legacy [`EventDecoder`] as a log-only reactive handler.
pub struct EventDecoderHandler {
    id: HandlerId,
    decoder: Arc<dyn EventDecoder>,
    interest: LogInterest,
}

impl EventDecoderHandler {
    /// Create an adapter from a decoder and log interest.
    pub fn new(id: HandlerId, decoder: Arc<dyn EventDecoder>, interest: LogInterest) -> Self {
        Self {
            id,
            decoder,
            interest,
        }
    }
}

impl<N: Network> ReactiveHandler<N> for EventDecoderHandler {
    fn id(&self) -> HandlerId {
        self.id.clone()
    }

    fn interests(&self) -> Vec<ReactiveInterest<N>> {
        vec![ReactiveInterest::Logs(self.interest.clone())]
    }

    fn handle(
        &self,
        _ctx: &ReactiveContext,
        input: &ReactiveInput<N>,
        state: &dyn StateView,
    ) -> Result<HandlerOutcome, HandlerError> {
        let ReactiveInput::Log(log) = input else {
            return Ok(HandlerOutcome::empty(StateEffectQuality::NoStateEffect));
        };

        Ok(HandlerOutcome {
            effects: self
                .decoder
                .decode(&log.inner, state)
                .into_iter()
                .map(ReactiveEffect::StateUpdate)
                .collect(),
            quality: StateEffectQuality::ExactFromInput,
            tags: Vec::new(),
        })
    }
}

/// One independently negotiable event-subscriber behavior.
#[derive(
    Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
#[non_exhaustive]
pub enum SubscriberCapability {
    /// Emit EVM logs.
    Logs,
    /// Emit block headers.
    BlockHeaders,
    /// Emit full blocks with transaction bodies.
    FullBlocks,
    /// Emit pending transaction hashes.
    PendingTransactionHashes,
    /// Emit hydrated pending transactions.
    PendingTransactions,
    /// Fetch historical data from a caller-selected anchor.
    HistoricalBackfill,
    /// Follow live chain data.
    Live,
    /// Recover the complete committed consumer position after reconnect or
    /// restart, including any unacknowledged delivery.
    ///
    /// An implementation may satisfy this with native stream replay or with a
    /// durable cursor plus deterministic historical reconciliation of an
    /// ephemeral live child. The end-to-end subscriber must still prove there
    /// is no gap between the restored position and resumed live delivery. If an
    /// old delivery token is emitted again, that token must identify the same
    /// immutable delivery and pass the engine's witness check.
    DurableReplay,
    /// Preserve logical handler ownership on delivered batches.
    OwnerScopedDelivery,
    /// Add and remove interests without replacing the complete session.
    DynamicInterests,
    /// Emit explicit canonical branch transitions.
    ExplicitReorgs,
    /// Emit safe and finalized head updates.
    FinalityUpdates,
    /// Emit ordered synchronization or source-cutover barriers.
    Barriers,
    /// Emit sequencer pre-confirmations into a disposable state overlay.
    Preconfirmations,
}

/// Capability set advertised by an [`EventSubscriber`].
///
/// The default is deliberately empty: callers can safely reject a topology
/// when an older or minimal implementation has not opted into a required
/// behavior.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SubscriberCapabilities {
    supported: BTreeSet<SubscriberCapability>,
}

impl SubscriberCapabilities {
    /// Construct a capability set from supported behaviors.
    pub fn new(capabilities: impl IntoIterator<Item = SubscriberCapability>) -> Self {
        Self {
            supported: capabilities.into_iter().collect(),
        }
    }

    /// Test one independently negotiable behavior.
    pub fn supports(&self, capability: SubscriberCapability) -> bool {
        self.supported.contains(&capability)
    }

    /// Iterate supported behaviors in stable order.
    pub fn iter(&self) -> impl Iterator<Item = SubscriberCapability> + '_ {
        self.supported.iter().copied()
    }

    /// Whether the subscriber follows live chain data.
    pub fn supports_live(&self) -> bool {
        self.supports(SubscriberCapability::Live)
    }

    /// Whether the subscriber can durably recover its committed position and
    /// any unacknowledged delivery without an event gap.
    pub fn supports_durable_replay(&self) -> bool {
        self.supports(SubscriberCapability::DurableReplay)
    }

    /// Whether the subscriber emits explicit branch transitions.
    pub fn supports_explicit_reorgs(&self) -> bool {
        self.supports(SubscriberCapability::ExplicitReorgs)
    }
}

impl FromIterator<SubscriberCapability> for SubscriberCapabilities {
    fn from_iter<T: IntoIterator<Item = SubscriberCapability>>(iter: T) -> Self {
        Self::new(iter)
    }
}

/// Provider-agnostic subscriber interface.
pub trait EventSubscriber<N: Network = Ethereum>: Send {
    /// Chain identity attached to emitted records, when it has been resolved.
    ///
    /// Remote and provider-backed subscribers should cache one authoritative
    /// identity before exposing input. Returning `None` is reserved for
    /// synthetic or genuinely chain-agnostic subscribers; composite sources
    /// can use this hook to reject accidentally mixed networks.
    fn chain_id(&self) -> Option<u64> {
        None
    }

    /// Behaviors this subscriber can uphold for topology validation.
    fn capabilities(&self) -> SubscriberCapabilities {
        SubscriberCapabilities::default()
    }

    /// Replace all interests registered with the subscriber.
    ///
    /// Implementations may use this as a full setup/reset operation. The
    /// in-crate [`AlloySubscriber`] clears owner-scoped interest state and
    /// delivery/dedupe bookkeeping when this method is called.
    ///
    /// The returned operation must complete only after the replacement has
    /// committed to the subscriber's desired state. Remote implementations can
    /// use this asynchronous boundary to wait for an authoritative service-side
    /// acknowledgement before returning `Ok(())`. On error, or when the future
    /// is dropped before completion, the previously committed desired state
    /// must remain authoritative (or be reconciled before later delivery can
    /// expose the uncommitted change) so callers can safely retry.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError`] when the replacement
    /// cannot be validated or committed by the underlying source.
    fn register_interests(
        &mut self,
        interests: &[ReactiveInterest<N>],
    ) -> SubscriberOperation<'_, ()>;

    /// Return the next input batch, or `Ok(None)` when the stream is exhausted.
    ///
    /// The returned future must be cancellation-safe: dropping it while pending
    /// must not discard a complete input that a later call could otherwise
    /// deliver. Composite subscribers use this property to race historical and
    /// live sources without dedicating a task to each transport.
    ///
    /// # Errors
    ///
    /// The returned future reports [`SubscriberError`] for transport,
    /// continuity, decoding, or source-resource failures.
    fn next_batch(&mut self) -> SubscriberNextBatch<'_, N>;

    /// Restore the subscriber's committed position before polling resumes.
    ///
    /// The engine invokes this synchronously from
    /// [`ReactiveEngine::resume_from_durable_checkpoint`] after decoding runtime
    /// recovery state and before publishing that state as resumed. Implementations
    /// should validate that provider/service cursors cannot regress and seed any
    /// source epoch or overlap history required for safe replay. A composite may
    /// rebuild an ephemeral live child from `coverage_head` plus historical
    /// reconciliation rather than require that child to replay bytes itself, but
    /// it may advertise [`SubscriberCapability::DurableReplay`] only when the
    /// complete restore closes that cutover gap before exposing live input. On
    /// error, either
    /// the prior position must remain authoritative, or the subscriber may retain
    /// this *exact* restore as pending intent; in the latter case it must block
    /// delivery and reject conflicting restores until retry/reconciliation commits
    /// the same position. This permits synchronous adapters over durable remote
    /// state without exposing a half-restored stream.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] when the position is invalid, regresses or
    /// conflicts with committed source state, or cannot be restored durably.
    fn restore_position(
        &mut self,
        _position: &SubscriberResumePosition,
    ) -> Result<(), SubscriberError> {
        Ok(())
    }

    /// Commit a subscriber-owned delivery token after runtime ingestion.
    ///
    /// Ephemeral subscribers can rely on this no-op default. Durable remote
    /// subscribers should make acknowledgement idempotent because cancellation
    /// or transport failure can cause a successfully ingested batch to replay.
    /// Re-emitting a token must reproduce the same immutable records, routing,
    /// chain controls, chain identity, and provider checkpoint; the checkpointed
    /// engine verifies its persisted delivery witness before skipping ingestion.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError`] when the delivery
    /// token cannot be committed idempotently by the source.
    fn acknowledge_delivery(
        &mut self,
        _token: SubscriberDeliveryToken,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async { Ok(()) })
    }
}

/// Boxed, sendable future returned by subscriber lifecycle operations.
///
/// The output is generic so the same type can represent registration, removal,
/// and future acknowledgement values without requiring an async-trait helper.
pub type SubscriberOperation<'a, T> =
    Pin<Box<dyn Future<Output = Result<T, SubscriberError>> + Send + 'a>>;

/// Boxed future returned by [`EventSubscriber::next_batch`].
pub type SubscriberNextBatch<'a, N> = Pin<
    Box<dyn Future<Output = Result<Option<ReactiveInputBatch<N>>, SubscriberError>> + Send + 'a>,
>;

/// Boxed future returned by [`AlloySubscriber::next_scoped_batch`].
pub type SubscriberNextScopedBatch<'a, N> = Pin<
    Box<dyn Future<Output = Result<Option<SubscriberInputBatch<N>>, SubscriberError>> + Send + 'a>,
>;

/// Subscriber mode requested for the Alloy subscriber.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum SubscriberMode {
    /// Prefer the default compiled transport.
    ///
    /// With the default `reactive-ws` feature this resolves to pubsub/WebSocket
    /// subscriptions. Without `reactive-ws`, it resolves to polling only when
    /// the opt-in `reactive-polling` feature is enabled.
    #[default]
    Auto,
    /// Use provider pubsub streams.
    PubSub,
    /// Use polling/watch APIs. Requires the `reactive-polling` feature.
    Polling,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum FlashblocksAdapter {
    BaseNative,
    OpPending,
}

fn flashblocks_adapter(chain_id: u64) -> Option<FlashblocksAdapter> {
    match chain_id {
        8_453 | 84_532 => Some(FlashblocksAdapter::BaseNative),
        10 | 11_155_420 => Some(FlashblocksAdapter::OpPending),
        _ => None,
    }
}

/// Subscriber configuration.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SubscriberConfig {
    /// Flashblocks delivery policy. Provider support itself is configured by
    /// the transport's single `flashblocks` endpoint flag.
    pub preconfirmations: PreconfirmationMode,
    /// OP pending-state sampling cadence. Base uses native `newFlashblocks`
    /// plus `pendingLogs` subscriptions instead.
    pub flashblock_poll_interval: Duration,
    /// Hydrate pending transaction hashes into full bodies when possible.
    pub hydrate_pending_transactions: bool,
    /// Verify each canonical log's block identity through RPC and enrich its
    /// context with the exact parent hash before delivery.
    ///
    /// Enable this when a strict coordinator (such as a hybrid historical/live
    /// source) must prove canonical ancestry from log-only pubsub events.
    /// Verification is cached per block, so the provider is queried at most
    /// once for each distinct canonical block retained in the dedupe window.
    /// For high-volume pubsub filters, configure
    /// [`AlloySubscriber::with_log_verification_provider`] with a separate HTTP
    /// provider so verification responses cannot be starved by notifications.
    pub verify_log_block_context: bool,
    /// Maximum records to emit per batch.
    pub max_batch_size: usize,
    /// Maximum distinct contract addresses placed in one provider-side log
    /// subscription. Compatible logical owner filters are fanned into address
    /// supersets up to this limit; exact owner routing still happens locally.
    pub max_log_addresses_per_subscription: usize,
    /// Maximum records retained across the delivery queue and hidden
    /// transaction-aware reconcile buffer. Exceeding it fails the subscriber
    /// closed until a full interest reset, because dropping an event would
    /// create an unknowable continuity gap.
    pub max_pending_records: usize,
    /// Maximum lazy owner-backfill requests retained at once.
    pub max_pending_backfills: usize,
    /// Maximum approximate encoded bytes accepted from one historical log
    /// response (fixed log identity fields, topics, and data).
    pub max_backfill_log_bytes: usize,
    /// Maximum provider log requests concurrently in flight during bulk owner
    /// reconciliation.
    pub max_reconcile_requests_in_flight: usize,
    /// Reconnect policy for WebSocket/pubsub streams.
    pub reconnect: SubscriberReconnectConfig,
}

impl Default for SubscriberConfig {
    fn default() -> Self {
        Self {
            preconfirmations: PreconfirmationMode::Disabled,
            flashblock_poll_interval: Duration::from_millis(100),
            hydrate_pending_transactions: false,
            verify_log_block_context: false,
            max_batch_size: 1024,
            max_log_addresses_per_subscription: 1024,
            max_pending_records: 16_384,
            max_pending_backfills: 4_096,
            max_backfill_log_bytes: 64 * 1024 * 1024,
            max_reconcile_requests_in_flight: 8,
            reconnect: SubscriberReconnectConfig::default(),
        }
    }
}

/// WebSocket/pubsub reconnect policy.
///
/// Reconnects are applied after an established subscription stream terminates.
/// Initial subscription failures are still returned immediately so deployment
/// mistakes, unsupported transports, and bad endpoints fail fast.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SubscriberReconnectConfig {
    /// Whether pubsub streams should be recreated after termination.
    pub enabled: bool,
    /// Delay before the first reconnect attempt.
    pub initial_delay: Duration,
    /// Delay before the second reconnect attempt. Later retries double this
    /// delay up to [`Self::max_delay`].
    pub retry_delay: Duration,
    /// Maximum delay between reconnect attempts.
    pub max_delay: Duration,
    /// Maximum reconnect attempts per terminated stream. `None` retries forever.
    pub max_attempts: Option<usize>,
    /// Number of recently emitted canonical input refs remembered to suppress
    /// duplicates across reconnect backfill and subscription replay.
    pub dedupe_window: usize,
}

impl Default for SubscriberReconnectConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            initial_delay: Duration::ZERO,
            retry_delay: Duration::from_millis(250),
            max_delay: Duration::from_secs(30),
            max_attempts: Some(3),
            dedupe_window: 4096,
        }
    }
}

/// Historical log backfill requested when adding subscriber interests.
///
/// Backfill applies only to [`ReactiveInterest::Logs`] entries. Block and
/// pending-transaction interests are live-only. `AlloySubscriber` emits records
/// fetched through this policy as [`InputSource::Backfill`]. Continuity-safe
/// owner registration adopts/subscribes the desired live filter first, then
/// reconciles history behind that live fence; startup/global replacement commits
/// topology and historical work as one desired-state transaction. A drained
/// backfill seeds the filter's delivery anchor at its resolved upper bound (even
/// when the window held no logs), so the newly added filter gets the same
/// reconnect/catch-up protection an established one has.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SubscriberBackfill {
    from_block: u64,
    to_block: Option<u64>,
    retained_anchor: Option<BlockRef>,
}

impl SubscriberBackfill {
    /// Backfill an inclusive block range.
    pub fn range(from_block: u64, to_block: u64) -> Self {
        Self {
            from_block,
            to_block: Some(to_block),
            retained_anchor: None,
        }
    }

    /// Backfill from `from_block` through the provider's latest block.
    pub fn from_block(from_block: u64) -> Self {
        Self {
            from_block,
            to_block: None,
            retained_anchor: None,
        }
    }

    /// Backfill inclusively from an exact retained canonical block.
    ///
    /// The Alloy subscriber verifies this number/hash against its provider
    /// before accepting any lazy catch-up response. Engine-managed mid-stream
    /// registration uses this form so owner replay cannot silently cross a
    /// reorged discovery boundary.
    pub fn from_canonical_block(block: BlockRef) -> Self {
        Self {
            from_block: block.number,
            to_block: None,
            retained_anchor: Some(block),
        }
    }

    /// Backfill inclusively from an exact canonical block through an inclusive
    /// upper bound.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError::InvalidConfig`] when `to_block` precedes the
    /// retained anchor.
    pub fn from_canonical_block_through(
        block: BlockRef,
        to_block: u64,
    ) -> Result<Self, SubscriberError> {
        if to_block < block.number {
            return Err(SubscriberError::InvalidConfig(
                "inclusive backfill upper bound precedes its retained anchor",
            ));
        }
        Ok(Self {
            from_block: block.number,
            to_block: Some(to_block),
            retained_anchor: Some(block),
        })
    }

    /// Backfill strictly after an exact canonical state baseline.
    ///
    /// This is distinct from [`from_canonical_block`](Self::from_canonical_block):
    /// a restored cache already embodies every effect through `block`, so
    /// replaying that block would apply it twice. The retained block is still
    /// carried so the subscriber can prove that its provider is on the same
    /// canonical branch before accepting any post-baseline history.
    ///
    /// Returns an error at `u64::MAX`; silently saturating would turn an empty
    /// exclusive range into an inclusive replay of the baseline block.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError::InvalidConfig`] when the baseline number is
    /// `u64::MAX` and therefore has no following block.
    pub fn after_canonical_block(block: BlockRef) -> Result<Self, SubscriberError> {
        Self::after_canonical_block_inner(block, None)
    }

    /// Backfill strictly after an exact canonical baseline through an
    /// inclusive upper bound.
    ///
    /// `to_block == block.number` represents a deliberately empty certified
    /// interval. Bounds before the retained baseline are rejected.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError::InvalidConfig`] when `to_block` precedes the
    /// baseline, or when a non-empty exclusive range would have to begin after
    /// block `u64::MAX`.
    pub fn after_canonical_block_through(
        block: BlockRef,
        to_block: u64,
    ) -> Result<Self, SubscriberError> {
        if to_block < block.number {
            return Err(SubscriberError::InvalidConfig(
                "exclusive backfill upper bound precedes its retained baseline",
            ));
        }
        Self::after_canonical_block_inner(block, Some(to_block))
    }

    fn after_canonical_block_inner(
        block: BlockRef,
        to_block: Option<u64>,
    ) -> Result<Self, SubscriberError> {
        let from_block = block
            .number
            .checked_add(1)
            .ok_or(SubscriberError::InvalidConfig(
                "cannot construct an exclusive backfill after block u64::MAX",
            ))?;
        Ok(Self {
            from_block,
            to_block,
            retained_anchor: Some(block),
        })
    }

    /// First block included in the backfill.
    pub fn start_block(&self) -> u64 {
        self.from_block
    }

    /// Last block included in the backfill, or `None` for provider latest.
    pub fn end_block(&self) -> Option<u64> {
        self.to_block
    }

    /// Exact retained start-block identity, when supplied.
    pub fn retained_anchor(&self) -> Option<&BlockRef> {
        self.retained_anchor.as_ref()
    }
}

/// Opaque generation for one transaction-aware subscriber interest owner.
///
/// Epochs are allocated monotonically by [`AlloySubscriber`] and are never
/// reused, including after an aborted stage or a full interest replacement.
/// Lifecycle operations require the complete token so a delayed command for an
/// older registration cannot affect a replacement using the same [`HandlerId`].
#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct SubscriberOwnerEpoch {
    owner: HandlerId,
    sequence: u64,
}

/// Delivery audience retained with a subscriber input record.
///
/// Canonical inputs are forwarded once to the runtime actor and may also name
/// staged epochs that need a buffered copy. Owner-only inputs are catch-up or
/// overlap records that must never be routed through existing canonical
/// handlers.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SubscriberInputScope {
    /// One canonical input plus any staged owners that matched at enqueue time.
    Canonical {
        /// Staged owner epochs that require a buffered copy.
        owners: Vec<SubscriberOwnerEpoch>,
    },
    /// Canonical input whose owner catch-up already delivered selected handler
    /// owners. The residual canonical copy must exclude those handlers while
    /// remaining authoritative for global chain progress.
    CanonicalResidual {
        /// Staged epoch owners that still require a buffered copy.
        owners: Vec<SubscriberOwnerEpoch>,
        /// Active compatibility owners already served by owner catch-up.
        excluded: Vec<HandlerId>,
    },
    /// Input delivered only to the listed staged owners.
    OwnerOnly {
        /// Exact staged owner epochs receiving the input.
        owners: Vec<SubscriberOwnerEpoch>,
    },
    /// Compatibility owner-only delivery keyed by stable handler id.
    OwnerOnlyHandlers {
        /// Exact active handlers receiving the catch-up input.
        owners: Vec<HandlerId>,
    },
    /// Flashblock input routed through ordinary matching handlers but applied
    /// only to the speculative overlay.
    Preconfirmed,
}

impl SubscriberInputScope {
    /// Exact staged owner epochs attached to this input.
    pub fn owners(&self) -> &[SubscriberOwnerEpoch] {
        match self {
            Self::Canonical { owners }
            | Self::CanonicalResidual { owners, .. }
            | Self::OwnerOnly { owners } => owners,
            Self::OwnerOnlyHandlers { .. } | Self::Preconfirmed => &[],
        }
    }

    /// Whether this input must be forwarded once through canonical routing.
    pub const fn is_canonical(&self) -> bool {
        matches!(
            self,
            Self::Canonical { .. } | Self::CanonicalResidual { .. }
        )
    }

    /// Whether this input belongs only to the disposable preconfirmed overlay.
    pub const fn is_preconfirmed(&self) -> bool {
        matches!(self, Self::Preconfirmed)
    }
}

/// Reactive input together with its canonical/owner-scoped delivery audience.
#[derive(Clone, Debug)]
pub struct SubscriberInputRecord<N: Network = Ethereum> {
    record: ReactiveInputRecord<N>,
    scope: SubscriberInputScope,
}

impl<N: Network> SubscriberInputRecord<N> {
    /// Borrow the reactive input record.
    pub const fn record(&self) -> &ReactiveInputRecord<N> {
        &self.record
    }

    /// Delivery audience captured when the record was enqueued.
    pub const fn scope(&self) -> &SubscriberInputScope {
        &self.scope
    }

    /// Consume the scoped value into its reactive input record.
    pub fn into_record(self) -> ReactiveInputRecord<N> {
        self.record
    }
}

impl<N: Network> std::ops::Deref for SubscriberInputRecord<N> {
    type Target = ReactiveInputRecord<N>;

    fn deref(&self) -> &Self::Target {
        &self.record
    }
}

/// Batch of subscriber inputs with enqueue-time owner provenance.
#[derive(Clone, Debug)]
pub struct SubscriberInputBatch<N: Network = Ethereum> {
    records: Vec<SubscriberInputRecord<N>>,
    chain_id: Option<u64>,
    chain_controls: Vec<ChainControl>,
}

/// Result of polling a scoped subscriber batch against one driver control
/// future.
#[derive(Debug)]
#[non_exhaustive]
pub enum SubscriberDriverPoll<C, N: Network = Ethereum> {
    /// The control future completed first; subscriber delivery remains intact.
    Control(C),
    /// Subscriber polling completed first.
    Batch(Option<SubscriberInputBatch<N>>),
}

impl<N: Network> SubscriberInputBatch<N> {
    /// Borrow every scoped record in delivery order.
    pub fn records(&self) -> &[SubscriberInputRecord<N>] {
        &self.records
    }

    /// Consume the batch into its scoped records.
    pub fn into_records(self) -> Vec<SubscriberInputRecord<N>> {
        self.records
    }

    /// Ordered chain controls committed after the preceding records.
    pub fn chain_controls(&self) -> &[ChainControl] {
        &self.chain_controls
    }

    /// Consume the scoped subscriber delivery into a runtime-ready batch.
    ///
    /// Delivery audiences and the preconfirmed/canonical boundary are retained,
    /// allowing downstream owner actors to forward a batch without rebuilding
    /// subscriber-internal scope metadata.
    pub fn into_reactive_batch(self) -> ReactiveInputBatch<N> {
        let chain_id = self.chain_id;
        let chain_controls = self.chain_controls;
        let mut batch = ReactiveInputBatch::from_scoped_records_with_delivery_scope(
            self.records.into_iter().map(|scoped| {
                let source = scoped.record.context.source;
                let (audience, delivery_scope) = match scoped.scope {
                    SubscriberInputScope::Canonical { .. } => (
                        DeliveryAudience::All,
                        if source == InputSource::Backfill {
                            DeliveryScope::CanonicalProgress
                        } else {
                            DeliveryScope::Canonical
                        },
                    ),
                    SubscriberInputScope::CanonicalResidual { excluded, .. } => (
                        DeliveryAudience::AllExcept(excluded),
                        if source == InputSource::Backfill {
                            DeliveryScope::CanonicalProgress
                        } else {
                            DeliveryScope::Canonical
                        },
                    ),
                    SubscriberInputScope::OwnerOnly { owners } => {
                        let mut handler_ids = Vec::with_capacity(owners.len());
                        for epoch in owners {
                            if !handler_ids.contains(epoch.owner()) {
                                handler_ids.push(epoch.owner().clone());
                            }
                        }
                        (
                            DeliveryAudience::Owners(handler_ids),
                            DeliveryScope::OwnerCatchup,
                        )
                    }
                    SubscriberInputScope::OwnerOnlyHandlers { owners } => (
                        DeliveryAudience::Owners(owners),
                        DeliveryScope::OwnerCatchup,
                    ),
                    SubscriberInputScope::Preconfirmed => {
                        (DeliveryAudience::All, DeliveryScope::Preconfirmed)
                    }
                };
                (scoped.record, audience, delivery_scope)
            }),
        )
        .with_chain_controls(chain_controls);
        if let Some(chain_id) = chain_id {
            batch = batch.with_chain_id(chain_id);
        }
        batch
    }
}

impl SubscriberOwnerEpoch {
    /// Logical subscriber owner represented by this epoch.
    pub const fn owner(&self) -> &HandlerId {
        &self.owner
    }

    /// Monotonic subscriber-local epoch sequence.
    pub const fn sequence(&self) -> u64 {
        self.sequence
    }
}

/// Catch-up policy applied when staging a transaction-aware interest owner.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum SubscriberOwnerStart {
    /// Start with live delivery only.
    Live,
    /// Start strictly after an already-applied post-block baseline.
    ///
    /// A baseline at block `N` schedules backfill from `N + 1`; block `N`
    /// itself is never replayed. Transaction-aware callers explicitly call
    /// [`AlloySubscriber::reconcile_interest_owner`] before activation; staged
    /// owners never use the legacy lazy-backfill queue.
    PostBlock(BlockRef),
}

/// Transaction state of one epoch-scoped subscriber owner.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SubscriberOwnerState {
    /// Desired interests and owner-scoped buffering are installed but canonical
    /// routing has not yet committed.
    Staged,
    /// Canonical runtime routing has committed for this owner.
    Active,
    /// Removal is prepared behind a delivery fence but remains reversible.
    Removing,
}

/// Hash-certified catch-up position reached by one subscriber owner epoch.
///
/// Progress means every owner-only record through this point has been fetched
/// and queued inside the subscriber. It does not mean the downstream actor has
/// drained or committed those records; that requires a separate delivery fence.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SubscriberOwnerProgress {
    owner: SubscriberOwnerEpoch,
    through: BlockRef,
}

impl SubscriberOwnerProgress {
    /// Exact owner epoch whose catch-up was reconciled.
    pub const fn owner(&self) -> &SubscriberOwnerEpoch {
        &self.owner
    }

    /// Verified canonical block through which owner input was fetched.
    pub const fn through(&self) -> &BlockRef {
        &self.through
    }
}

/// Error staging a transaction-aware subscriber owner.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SubscriberOwnerError {
    /// Subscriber configuration or interest validation failed.
    #[error(transparent)]
    Subscriber(#[from] SubscriberError),
    /// The logical owner already has desired interests installed.
    #[error("subscriber interest owner `{0}` is already registered")]
    AlreadyRegistered(HandlerId),
    /// A post-block baseline cannot be advanced to its first unapplied block.
    #[error("post-block subscriber baseline {0} has no following block")]
    PostBlockOverflow(u64),
    /// The monotonic subscriber owner epoch sequence was exhausted.
    #[error("subscriber owner epoch sequence exhausted")]
    EpochExhausted,
    /// The exact owner epoch is unknown or no longer staged.
    #[error("subscriber owner epoch is not staged")]
    NotStaged,
    /// Live-only staging has no historical baseline to reconcile.
    #[error("subscriber owner was staged live-only and has no catch-up baseline")]
    MissingBaseline,
    /// Post-block reconciliation currently covers log interests only.
    #[error("post-block subscriber owners support log interests only")]
    UnsupportedPostBlockInterest,
    /// The target block was absent from the provider.
    #[error("subscriber reconcile target block {0} was not found")]
    BlockUnavailable(u64),
    /// The provider's canonical identity did not match the requested target.
    #[error(
        "subscriber reconcile target mismatch: expected block {expected_number} {expected_hash}, got block {actual_number} {actual_hash}"
    )]
    BlockMismatch {
        /// Requested block number.
        expected_number: u64,
        /// Requested block hash.
        expected_hash: B256,
        /// Provider block number.
        actual_number: u64,
        /// Provider block hash.
        actual_hash: B256,
    },
    /// A reconcile target was older than the retained baseline/progress.
    #[error("subscriber reconcile target block {target} precedes current owner position {current}")]
    ProgressRegression {
        /// Retained baseline or progress block.
        current: u64,
        /// Rejected target block.
        target: u64,
    },
    /// A reconcile attempted to replace a retained block identity at the same
    /// height or cross an immediate parent that does not extend it.
    #[error(
        "subscriber reconcile conflicts with retained block {number} {current_hash}: target chain references {target_hash}"
    )]
    ProgressConflict {
        /// Retained baseline or progress block number.
        number: u64,
        /// Retained baseline or progress block hash.
        current_hash: B256,
        /// Conflicting target hash or immediate parent hash.
        target_hash: B256,
    },
    /// A provider returned a malformed or out-of-range catch-up log.
    #[error("subscriber reconcile returned an invalid catch-up log: {0}")]
    InvalidBackfillLog(&'static str),
}

/// Extension trait for subscribers that can add and remove handler-owned
/// interests incrementally.
///
/// [`EventSubscriber::register_interests`] remains the full-replacement setup
/// API. Implement this trait when a subscriber can preserve unrelated live
/// sources and delivery state while one handler's interests are added or
/// removed. Implementations should make owner *replacement* continuity-safe:
/// updating an owner's interests must not silently discard delivery progress
/// the previous interests had already established (the in-crate
/// [`AlloySubscriber`] carries the owner's prior delivery anchor over to
/// changed filter shapes and automatically backfills the gap). Every mutating
/// operation is also a commit boundary: returning `Ok` means the new desired
/// state is authoritative, while errors or cancellation must preserve the
/// previous state or reconcile before exposing the uncommitted change.
pub trait InterestOwnerSubscriber<N: Network = Ethereum>: EventSubscriber<N> {
    /// Atomically add or replace several owners in one desired-state revision.
    ///
    /// Unrelated owners remain installed. Returning `Ok(())` is one commit
    /// boundary for the complete set; an error or cancellation must leave the
    /// previously committed owner topology authoritative. Durable remote
    /// subscribers should override this method so bootstrap creates one service
    /// revision and one activation barrier rather than one barrier per owner.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError::Unsupported`] by
    /// default, or an implementation-specific validation or commit failure.
    fn upsert_interest_owners(
        &mut self,
        _owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async {
            Err(SubscriberError::Unsupported(
                "subscriber does not implement atomic bulk owner upsert",
            ))
        })
    }

    /// Atomically replace the complete engine-managed owner topology without
    /// requesting history.
    ///
    /// This is the fresh-runtime bootstrap operation. Base/unowned interests,
    /// stale owners, queued delivery, and dedupe/source state from the prior
    /// topology must not survive a successful replacement. Errors and dropped
    /// futures leave the prior committed topology authoritative.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError::Unsupported`] by
    /// default, or an implementation-specific validation or commit failure.
    fn replace_interest_owners(
        &mut self,
        _owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async {
            Err(SubscriberError::Unsupported(
                "subscriber does not implement atomic exact owner replacement",
            ))
        })
    }

    /// Atomically replace the complete owner set and schedule one global
    /// historical log backfill in the same desired-state revision.
    ///
    /// This is the continuity-safe bootstrap operation for a runtime that has
    /// already processed canonical state while the subscriber's owner state is
    /// new or may have been lost. Implementations must commit the complete
    /// owner topology and all required historical work together: returning an
    /// error or dropping the future must leave the previously committed state
    /// authoritative. The default is deliberately unsupported rather than a
    /// sequence of partially committed single-owner updates.
    /// Historical records must be delivered through canonical global routing
    /// (`DeliveryAudience::All` / `DeliveryScope::CanonicalProgress`), not as
    /// owner catch-up, so their effects participate in the normal rollback
    /// journal before the source certifies the cutover. Base/unowned interests
    /// are replaced by this complete engine-managed topology. Any owner absent
    /// from `owners` must be removed together with its queued owner-only work, which closes
    /// the crash window where a subscriber committed registration but the
    /// runtime process died before installing the corresponding handler.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError::Unsupported`] by
    /// default, or a backfill, validation, transport, or atomic-commit failure.
    fn replace_interest_owners_with_global_backfill(
        &mut self,
        _owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        _backfill: SubscriberBackfill,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async {
            Err(SubscriberError::Unsupported(
                "subscriber does not implement atomic owner replacement with global backfill",
            ))
        })
    }

    /// Add or replace the interests owned by `owner`, awaiting the subscriber's
    /// commit boundary.
    ///
    /// Implementations must leave the previously committed owner state
    /// authoritative when the operation returns an error or is cancelled before
    /// completion.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError`] when the owner update
    /// cannot be validated or committed.
    fn add_interest_owner(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
    ) -> SubscriberOperation<'_, ()>;

    /// Add or replace owner interests and schedule log backfill for that owner,
    /// awaiting the subscriber's commit boundary.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError`] when the owner update
    /// or requested backfill cannot be validated or committed.
    fn add_interest_owner_with_backfill(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        backfill: SubscriberBackfill,
    ) -> SubscriberOperation<'_, ()>;

    /// Add a handler discovered at retained canonical block `C` without
    /// opening a gap while registration commits.
    ///
    /// The subscriber must subscribe/adopt the new desired state first, then
    /// expose the new owner's matching records from `C` as owner catch-up and
    /// expose `C + 1` through the activation head as one globally ordered
    /// canonical catch-up over the complete active interest union. This split
    /// is deliberate: the runtime already has a rollback entry for `C`, while
    /// later blocks must run every handler and create normal canonical journal
    /// entries. Errors/cancellation preserve the prior committed topology.
    /// Implementations that cannot uphold this coordinated transaction must
    /// return `Unsupported`; emitting owner-only records past `C` is invalid.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError::Unsupported`] by
    /// default, or a canonical-anchor, transport, or atomic-commit failure.
    fn add_interest_owner_with_canonical_catchup(
        &mut self,
        _owner: HandlerId,
        _interests: &[ReactiveInterest<N>],
        _retained: BlockRef,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async {
            Err(SubscriberError::Unsupported(
                "subscriber does not implement coordinated canonical owner catch-up",
            ))
        })
    }

    /// Remove one owner's interests, preserving unrelated interests, and await
    /// acknowledgement that the removal committed.
    ///
    /// On error the owner must remain authoritative, so the runtime handler is
    /// not removed while subscriber delivery may still target it.
    ///
    /// # Errors
    ///
    /// The returned operation reports [`SubscriberError`] when the removal
    /// cannot be committed while preserving unrelated owners.
    fn remove_interest_owner(
        &mut self,
        owner: &HandlerId,
    ) -> SubscriberOperation<'_, Option<Vec<ReactiveInterest<N>>>>;

    /// Borrow the interests currently owned by `owner`.
    fn owner_interests(&self, owner: &HandlerId) -> Option<&[ReactiveInterest<N>]>;
}

/// Binds a [`ReactiveRuntime`] to an [`EventSubscriber`] for the common
/// subscribe-ingest lifecycle.
///
/// The engine treats the runtime registry as the single source of truth for
/// handler lifecycle: [`register_handler`](Self::register_handler) and
/// [`unregister_handler`](Self::unregister_handler) update runtime routing and
/// subscriber interests as one operation, keyed by the handler's stable
/// [`HandlerId`]. Registration is continuity-safe by default — once the runtime
/// has journaled canonical block *N*, a newly registered handler is live-adopted,
/// replayed owner-only at *N*, and then caught up globally with every handler
/// from *N + 1* through activation. A factory-discovered pool therefore misses
/// none of its own logs without making later history owner-local and
/// unrollbackable. The subscriber must absorb overlap that crosses batch
/// boundaries; the runtime validates and merges duplicate representations only
/// within one [`ReactiveInputBatch`].
///
/// Registration methods by intent:
///
/// | Method | Backfill |
/// |---|---|
/// | [`register_handler`](Self::register_handler) | coordinated owner replay at the last retained block plus global catch-up above it (live-only on a fresh runtime) |
/// | [`register_handler_with_backfill`](Self::register_handler_with_backfill) | exactly one hash-certified block still retained by the rollback journal |
/// | [`register_handler_live_only`](Self::register_handler_live_only) | none — future logs only |
///
/// Unregistering a handler stops future subscription routing and runtime
/// decode for that handler; it deliberately does not evict [`EvmCache`] state
/// or undo runtime side effects. See
/// [`unregister_handler`](Self::unregister_handler) for the complete teardown
/// recipe.
///
/// The runtime and subscriber stay independently accessible through
/// [`runtime_mut`](Self::runtime_mut) / [`subscriber_mut`](Self::subscriber_mut)
/// for advanced use. One caution: avoid calling
/// [`EventSubscriber::register_interests`] (the full-replacement setup API) on
/// an engine-managed subscriber — implementations may clear owner-scoped
/// bookkeeping, after which per-handler unregistration no longer releases the
/// handler's transport subscriptions. To bootstrap the subscriber from a
/// runtime that already has handlers, use
/// [`sync_handler_interests`](Self::sync_handler_interests), which registers
/// one owner per handler instead of one unowned blob.
pub struct ReactiveEngine<S, N: Network = Ethereum> {
    runtime: ReactiveRuntime<N>,
    subscriber: S,
    pending_acknowledgement: Option<PendingAcknowledgement<N>>,
    pending_checkpoint: Option<PendingCheckpoint<N>>,
    last_checkpoint_block: Option<DurableCheckpointBlock>,
    last_checkpoint_delivery_token: Option<SubscriberDeliveryToken>,
    last_checkpoint_delivery_witness: Option<B256>,
    last_subscriber_checkpoint: Option<SubscriberCheckpoint>,
    checkpoint_identity: Option<DurableCheckpointIdentity>,
}

struct PendingAcknowledgement<N: Network> {
    token: SubscriberDeliveryToken,
    report: ReactiveBatchReport<N>,
}

struct PendingCheckpoint<N: Network> {
    metadata: DurableCheckpointMetadata,
    delivery_token: Option<SubscriberDeliveryToken>,
    report: ReactiveBatchReport<N>,
    saved_to: Option<PathBuf>,
    staged_generation: u64,
}

struct CheckpointStage<N: Network> {
    incoming_block: Option<DurableCheckpointBlock>,
    delivery_token: Option<SubscriberDeliveryToken>,
    delivery_witness: Option<B256>,
    subscriber_checkpoint: Option<SubscriberCheckpoint>,
    staged_generation: u64,
    report: ReactiveBatchReport<N>,
}

struct DurableResumePlan {
    runtime: DurableRuntimeRestorePlan,
    position: SubscriberResumePosition,
    delivery_witness: Option<B256>,
}

enum HandlerRegistrationCatchup {
    LiveOnly,
    OwnerBackfill(SubscriberBackfill),
    CoordinatedCanonical(BlockRef),
}

const DELIVERY_WITNESS_VERSION: u32 = 1;
const DELIVERY_WITNESS_DOMAIN: &[u8] = b"evm-fork-cache/reactive-delivery-witness";

#[derive(serde::Serialize)]
struct DeliveryWitnessEnvelope<'a> {
    version: u32,
    chain_id: Option<u64>,
    records: Vec<DeliveryRecordWitness<'a>>,
    chain_controls: &'a [ChainControl],
    subscriber_checkpoint: Option<&'a [u8]>,
    payload_commitment: Option<B256>,
}

#[derive(serde::Serialize)]
struct DeliveryRecordWitness<'a> {
    identity: ReactiveInputIdentity,
    context: &'a ReactiveContext,
    audience: &'a DeliveryAudience,
    scope: DeliveryScope,
    payload: DeliveryPayloadWitness<'a>,
}

#[derive(serde::Serialize)]
enum DeliveryPayloadWitness<'a> {
    /// Logs are the primary state-bearing event representation, so retain every
    /// RPC payload field in addition to the validated identity/context.
    Log {
        address: Address,
        topics: &'a [B256],
        data: &'a Bytes,
        block_hash: Option<B256>,
        block_number: Option<u64>,
        block_timestamp: Option<u64>,
        transaction_hash: Option<B256>,
        transaction_index: Option<u64>,
        log_index: Option<u64>,
        removed: bool,
    },
    /// Network-generic response bodies do not expose one stable complete serde
    /// contract. Their validated identity/context are witnessed here; batches
    /// containing headers, full blocks, or hydrated transactions additionally
    /// require the source's exact canonical wire-payload commitment. A generic
    /// header response can expose a supplied hash without proving that every
    /// handler-visible inner field recomputes to it.
    IdentityCommitted,
}

fn durable_delivery_witness<N: Network>(
    batch: &ReactiveInputBatch<N>,
) -> Result<B256, ReactiveEngineError> {
    let requires_payload_commitment = batch.records.iter().any(|record| {
        matches!(
            &record.input,
            ReactiveInput::BlockHeader(_)
                | ReactiveInput::FullBlock(_)
                | ReactiveInput::PendingTx(_)
        )
    });
    if requires_payload_commitment && batch.payload_commitment.is_none() {
        return Err(ReactiveEngineError::MissingPayloadCommitment);
    }
    let records = batch
        .records
        .iter()
        .enumerate()
        .map(|(index, record)| {
            let payload = match &record.input {
                ReactiveInput::Log(log) => DeliveryPayloadWitness::Log {
                    address: log.address(),
                    topics: log.topics(),
                    data: &log.inner.data.data,
                    block_hash: log.block_hash,
                    block_number: log.block_number,
                    block_timestamp: log.block_timestamp,
                    transaction_hash: log.transaction_hash,
                    transaction_index: log.transaction_index,
                    log_index: log.log_index,
                    removed: log.removed,
                },
                ReactiveInput::BlockHeader(_)
                | ReactiveInput::FullBlock(_)
                | ReactiveInput::PendingTxHash(_)
                | ReactiveInput::PendingTx(_) => DeliveryPayloadWitness::IdentityCommitted,
            };
            Ok(DeliveryRecordWitness {
                identity: record.validated_identity()?,
                context: &record.context,
                audience: batch
                    .record_audience(index)
                    .expect("enumerated record always has an audience"),
                scope: batch
                    .record_delivery_scope(index)
                    .expect("enumerated record always has a delivery scope"),
                payload,
            })
        })
        .collect::<Result<Vec<_>, ReactiveError>>()?;
    let envelope = DeliveryWitnessEnvelope {
        version: DELIVERY_WITNESS_VERSION,
        chain_id: batch.chain_id,
        records,
        chain_controls: &batch.chain_controls,
        subscriber_checkpoint: batch
            .subscriber_checkpoint
            .as_ref()
            .map(SubscriberCheckpoint::as_bytes),
        payload_commitment: batch
            .payload_commitment
            .as_ref()
            .map(SubscriberPayloadCommitment::digest),
    };
    let encoded = bincode::DefaultOptions::new()
        .with_fixint_encoding()
        .serialize(&envelope)
        .map_err(|error| ReactiveEngineError::DeliveryWitness(error.to_string()))?;
    let mut witness = Keccak256::new();
    witness.update(DELIVERY_WITNESS_DOMAIN);
    witness.update(encoded);
    Ok(witness.finalize())
}

impl<S, N> ReactiveEngine<S, N>
where
    N: Network,
    S: EventSubscriber<N>,
{
    /// Bind a runtime and subscriber.
    pub fn new(runtime: ReactiveRuntime<N>, subscriber: S) -> Self {
        Self {
            runtime,
            subscriber,
            pending_acknowledgement: None,
            pending_checkpoint: None,
            last_checkpoint_block: None,
            last_checkpoint_delivery_token: None,
            last_checkpoint_delivery_witness: None,
            last_subscriber_checkpoint: None,
            checkpoint_identity: None,
        }
    }

    /// Split the engine into its runtime and subscriber parts when no commit is
    /// pending.
    ///
    /// A failed delivery acknowledgement or durable checkpoint commit remains
    /// live protocol state: dropping it would allow the caller to lose the
    /// already-applied report/token pair and poll past an uncommitted batch.
    /// In that case this returns the intact engine so the caller can repair the
    /// dependency and retry through the normal ingestion method.
    ///
    /// # Errors
    ///
    /// Returns the intact boxed engine when an acknowledgement or checkpoint
    /// commit is pending.
    pub fn into_parts(self) -> Result<(ReactiveRuntime<N>, S), Box<Self>> {
        if self.pending_acknowledgement.is_some() || self.pending_checkpoint.is_some() {
            return Err(Box::new(self));
        }
        Ok((self.runtime, self.subscriber))
    }

    fn durable_resume_plan(
        &self,
        metadata: &DurableCheckpointMetadata,
    ) -> Result<DurableResumePlan, ReactiveCheckpointRestoreError> {
        if !self.subscriber.capabilities().supports_durable_replay() {
            return Err(ReactiveCheckpointRestoreError::SubscriberNotDurable);
        }
        self.ensure_subscriber_restore_chain(metadata.identity.chain_id)?;
        if !self.runtime.is_pristine_for_checkpoint_restore()
            || self.pending_acknowledgement.is_some()
            || self.pending_checkpoint.is_some()
            || self.last_checkpoint_block.is_some()
            || self.last_checkpoint_delivery_token.is_some()
            || self.last_checkpoint_delivery_witness.is_some()
            || self.last_subscriber_checkpoint.is_some()
            || self.checkpoint_identity.is_some()
        {
            return Err(ReactiveCheckpointRestoreError::ActiveRuntime);
        }

        let block = BlockRef {
            number: metadata.block.number,
            hash: metadata.block.hash,
            parent_hash: metadata.block.parent_hash,
            timestamp: metadata.block.timestamp,
        };
        let runtime = match metadata.runtime_checkpoint.as_deref() {
            Some(bytes) => self
                .runtime
                .plan_durable_checkpoint_restore(bytes, &block)?,
            None => DurableRuntimeRestorePlan {
                checkpoint: None,
                fallback_history: (self.runtime.config.journal_depth > 0)
                    .then_some(block)
                    .into_iter()
                    .collect(),
            },
        };
        let delivery_token = metadata
            .delivery_token
            .clone()
            .map(SubscriberDeliveryToken::new);
        let subscriber_checkpoint = metadata
            .subscriber_checkpoint
            .clone()
            .map(SubscriberCheckpoint::new);
        let position = SubscriberResumePosition::new(
            metadata.identity.chain_id,
            block,
            runtime.canonical_history(),
            delivery_token,
            subscriber_checkpoint,
        );
        Ok(DurableResumePlan {
            runtime,
            position,
            delivery_witness: metadata.delivery_witness,
        })
    }

    /// Preview the exact subscriber position a durable restore will install.
    ///
    /// This read-only step exists for durable subscribers that must complete
    /// asynchronous source or transport preparation before the engine invokes
    /// the synchronous [`EventSubscriber::restore_position`] hook. It decodes
    /// and validates the core runtime checkpoint, applies this runtime's
    /// configured journal retention to the preview, and returns the same
    /// [`SubscriberResumePosition`] that
    /// [`resume_from_durable_checkpoint`](Self::resume_from_durable_checkpoint)
    /// will later pass to the subscriber.
    ///
    /// Call this on the same fresh engine that will perform the restore. After
    /// subscriber preparation completes, pass the identical `metadata` to
    /// `resume_from_durable_checkpoint` (or restore the same loaded checkpoint
    /// through [`restore_durable_checkpoint`](Self::restore_durable_checkpoint))
    /// without mutating engine runtime or checkpoint state in between. The
    /// checkpoint identity and, for non-finalized state, its canonical block
    /// must still be validated by the caller before external preparation.
    ///
    /// This method does not mutate the runtime, subscriber, or checkpoint
    /// bookkeeping.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveCheckpointRestoreError`] when the subscriber is not
    /// durable, its chain identity conflicts with the checkpoint, the engine is
    /// not fresh, or the stored runtime checkpoint is malformed, unsupported,
    /// or internally inconsistent.
    pub fn preview_durable_resume_position(
        &self,
        metadata: &DurableCheckpointMetadata,
    ) -> Result<SubscriberResumePosition, ReactiveCheckpointRestoreError> {
        Ok(self.durable_resume_plan(metadata)?.position)
    }

    /// Resume delivery bookkeeping and canonical continuity from a cache
    /// checkpoint that has already been identity- and hash-validated and
    /// restored into [`EvmCache`].
    ///
    /// Call this on a fresh engine. The anchor has no rollback effects of its
    /// own: it represents the state baseline embodied by the checkpoint, while
    /// newly ingested blocks are journaled normally above it.
    /// The subscriber must advertise [`SubscriberCapability::DurableReplay`];
    /// restoring an ephemeral stream would claim a restart guarantee it cannot
    /// uphold and is rejected before cache or runtime mutation.
    ///
    /// Prefer [`restore_durable_checkpoint`](Self::restore_durable_checkpoint)
    /// when the cache has not yet been restored: that helper rolls the cache
    /// back as well if runtime or subscriber activation fails.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveCheckpointRestoreError`] when the subscriber is not
    /// durable, chain identity conflicts, the runtime is not pristine, stored
    /// runtime state is invalid, or the subscriber rejects the restored
    /// position. Runtime state is restored on subscriber failure.
    pub fn resume_from_durable_checkpoint(
        &mut self,
        metadata: &DurableCheckpointMetadata,
    ) -> Result<(), ReactiveCheckpointRestoreError> {
        let plan = self.durable_resume_plan(metadata)?;
        let prior_runtime = self.runtime.checkpoint_state();

        let DurableResumePlan {
            runtime,
            position,
            delivery_witness,
        } = plan;
        self.runtime.apply_durable_checkpoint_restore(runtime);
        self.runtime.coverage_head = Some(position.coverage_head);
        if let Err(error) = self.subscriber.restore_position(&position) {
            self.runtime.restore_state(prior_runtime);
            return Err(ReactiveCheckpointRestoreError::Subscriber(error));
        }
        if let Err(error) = self.ensure_subscriber_restore_chain(metadata.identity.chain_id) {
            self.runtime.restore_state(prior_runtime);
            return Err(error);
        }
        self.last_checkpoint_block = Some(metadata.block.clone());
        self.last_checkpoint_delivery_token = position.delivery_token;
        self.last_checkpoint_delivery_witness = delivery_witness;
        self.last_subscriber_checkpoint = position.subscriber_checkpoint;
        self.checkpoint_identity = Some(metadata.identity.clone());
        Ok(())
    }

    /// Atomically restore cache, runtime, and subscriber position from one
    /// validated durable checkpoint.
    ///
    /// Inspect [`LoadedDurableCheckpoint::metadata`] and validate its canonical
    /// block against an authoritative RPC source before calling this method when
    /// the block is not finalized. Identity, cache-chain, runtime-state, and
    /// subscriber failures leave the cache and engine runtime unchanged. The
    /// subscriber follows [`EventSubscriber::restore_position`]'s retry contract.
    /// It must advertise [`SubscriberCapability::DurableReplay`].
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveCheckpointRestoreError`] for checkpoint identity,
    /// cache-chain, runtime-state, subscriber-capability, subscriber-chain, or
    /// position-restore failures. Cache and runtime state remain unchanged.
    pub fn restore_durable_checkpoint(
        &mut self,
        cache: &mut EvmCache,
        loaded: LoadedDurableCheckpoint,
        expected: &DurableCheckpointIdentity,
    ) -> Result<DurableCheckpointMetadata, ReactiveCheckpointRestoreError> {
        if !self.subscriber.capabilities().supports_durable_replay() {
            return Err(ReactiveCheckpointRestoreError::SubscriberNotDurable);
        }
        self.ensure_subscriber_restore_chain(expected.chain_id)?;
        if !self.runtime.is_pristine_for_checkpoint_restore()
            || self.pending_acknowledgement.is_some()
            || self.pending_checkpoint.is_some()
            || self.last_checkpoint_block.is_some()
            || self.last_checkpoint_delivery_token.is_some()
            || self.last_checkpoint_delivery_witness.is_some()
            || self.last_subscriber_checkpoint.is_some()
            || self.checkpoint_identity.is_some()
        {
            return Err(ReactiveCheckpointRestoreError::ActiveRuntime);
        }

        let prior_cache = EvmCacheStateSnapshot::capture(cache);
        let metadata = loaded.restore_into(cache, expected)?;
        if let Err(error) = self.resume_from_durable_checkpoint(&metadata) {
            prior_cache.restore(cache);
            return Err(error);
        }
        Ok(metadata)
    }

    /// Borrow the runtime.
    pub fn runtime(&self) -> &ReactiveRuntime<N> {
        &self.runtime
    }

    /// Mutably borrow the runtime.
    pub fn runtime_mut(&mut self) -> &mut ReactiveRuntime<N> {
        &mut self.runtime
    }

    /// Borrow the subscriber.
    pub fn subscriber(&self) -> &S {
        &self.subscriber
    }

    /// Mutably borrow the subscriber.
    pub fn subscriber_mut(&mut self) -> &mut S {
        &mut self.subscriber
    }

    /// Adopt a hash-pinned RPC cache snapshot as the runtime's canonical
    /// cold-start baseline.
    ///
    /// The cache must use the exact canonical hash selector and block-number
    /// context named by `baseline`; when the baseline includes a timestamp, the
    /// cache timestamp must match too. Cache, baseline, and any already-resolved
    /// subscriber identity must name the same chain. No delivery or checkpoint
    /// commit may be pending. After this succeeds, call
    /// [`sync_handler_interests_with_backfill`](Self::sync_handler_interests_with_backfill)
    /// before polling: it exact-replaces subscriber owners and begins event
    /// catch-up at `C + 1`.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] when commit state is pending, the runtime
    /// is active or already has a conflicting baseline, cache/subscriber chain
    /// identity differs, or the cache is not pinned to the exact baseline.
    pub fn adopt_canonical_baseline(
        &mut self,
        cache: &EvmCache,
        baseline: ReactiveCanonicalBaseline,
    ) -> Result<(), ReactiveEngineError> {
        if self.pending_acknowledgement.is_some()
            || self.pending_checkpoint.is_some()
            || self.last_checkpoint_block.is_some()
            || self.last_checkpoint_delivery_token.is_some()
            || self.last_checkpoint_delivery_witness.is_some()
            || self.last_subscriber_checkpoint.is_some()
            || self.checkpoint_identity.is_some()
        {
            return Err(ReactiveBaselineError::ActiveRuntime.into());
        }
        // Establish deterministic lifecycle/idempotency semantics before
        // consulting mutable cache context. A conflicting repeat is a runtime
        // baseline conflict even if the caller also repointed the cache.
        self.runtime
            .validate_canonical_baseline_adoption(baseline.block)?;
        if baseline.chain_id != cache.chain_id() {
            return Err(ReactiveBaselineError::CacheChainMismatch {
                baseline_chain_id: baseline.chain_id,
                cache_chain_id: cache.chain_id(),
            }
            .into());
        }
        self.ensure_subscriber_chain(cache)?;
        let exact_selector = BlockId::from((baseline.block.hash, Some(true)));
        let context_matches = cache.block_number() == Some(baseline.block.number)
            && baseline
                .block
                .timestamp
                .is_none_or(|timestamp| cache.timestamp() == Some(timestamp));
        if cache.block() != exact_selector || !context_matches {
            return Err(ReactiveBaselineError::CacheBlockMismatch {
                number: baseline.block.number,
                hash: baseline.block.hash,
            }
            .into());
        }
        self.runtime.adopt_canonical_baseline(baseline.block)?;
        Ok(())
    }

    /// Poll the subscriber for the next batch without ingesting it.
    ///
    /// This low-level escape hatch is unavailable while the engine owes an
    /// acknowledgement or checkpoint commit. Callers that use it must return
    /// any subscriber-owned delivery metadata through a combined
    /// [`next_ingest`](Self::next_ingest) helper; raw ingestion deliberately
    /// rejects that metadata so it cannot be discarded accidentally.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] when an acknowledgement/checkpoint commit
    /// is pending or subscriber and cache chain identities conflict.
    pub fn next_batch(
        &mut self,
        cache: &EvmCache,
    ) -> Result<SubscriberNextBatch<'_, N>, ReactiveEngineError> {
        if self.pending_checkpoint.is_some() {
            return Err(ReactiveEngineError::PendingCheckpointCommit);
        }
        if self.pending_acknowledgement.is_some() {
            return Err(ReactiveEngineError::PendingAcknowledgementCommit);
        }
        self.ensure_subscriber_chain(cache)?;
        Ok(self.subscriber.next_batch())
    }

    /// Ingest one already-polled batch through the runtime (direct effects
    /// only; surfaced resync requests are reported, not executed).
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] when commit state is pending, the batch
    /// carries subscriber-owned commit metadata, chain identity conflicts, or
    /// runtime ingestion fails.
    pub fn ingest_batch(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveEngineError> {
        self.ensure_raw_ingest_is_safe(cache, &batch)?;
        Ok(self.runtime.ingest_batch(cache, batch)?)
    }

    /// Ingest one already-polled batch and execute the storage/account resyncs
    /// it surfaces, exactly like
    /// [`ReactiveRuntime::ingest_batch_with_resync`].
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] when commit state is pending, the batch
    /// carries subscriber-owned commit metadata, chain identity conflicts, or
    /// runtime ingestion fails.
    pub fn ingest_batch_with_resync(
        &mut self,
        cache: &mut EvmCache,
        batch: ReactiveInputBatch<N>,
    ) -> Result<ReactiveBatchReport<N>, ReactiveEngineError> {
        self.ensure_raw_ingest_is_safe(cache, &batch)?;
        Ok(self.runtime.ingest_batch_with_resync(cache, batch)?)
    }

    fn ensure_raw_ingest_is_safe(
        &self,
        cache: &EvmCache,
        batch: &ReactiveInputBatch<N>,
    ) -> Result<(), ReactiveEngineError> {
        if self.pending_checkpoint.is_some() {
            return Err(ReactiveEngineError::PendingCheckpointCommit);
        }
        if self.pending_acknowledgement.is_some() {
            return Err(ReactiveEngineError::PendingAcknowledgementCommit);
        }
        if batch.delivery_token().is_some() || batch.subscriber_checkpoint().is_some() {
            return Err(ReactiveEngineError::UncommittedDeliveryMetadata);
        }
        self.ensure_subscriber_chain(cache)?;
        Ok(())
    }

    fn ensure_subscriber_chain(&self, cache: &EvmCache) -> Result<(), ReactiveEngineError> {
        if let Some(subscriber_chain_id) = self.subscriber.chain_id()
            && subscriber_chain_id != cache.chain_id()
        {
            return Err(ReactiveEngineError::SubscriberChainMismatch {
                subscriber_chain_id,
                cache_chain_id: cache.chain_id(),
            });
        }
        Ok(())
    }

    fn ensure_subscriber_restore_chain(
        &self,
        checkpoint_chain_id: u64,
    ) -> Result<(), ReactiveCheckpointRestoreError> {
        if let Some(subscriber_chain_id) = self.subscriber.chain_id()
            && subscriber_chain_id != checkpoint_chain_id
        {
            return Err(ReactiveCheckpointRestoreError::SubscriberChainMismatch {
                subscriber_chain_id,
                checkpoint_chain_id,
            });
        }
        Ok(())
    }

    /// Poll the subscriber once and ingest the returned batch when present
    /// (direct effects only).
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] for subscriber/cache chain mismatch,
    /// pending checkpoint state, subscriber polling, runtime ingestion, or
    /// delivery-acknowledgement failure. A failed acknowledgement remains
    /// pending and is retried before polling again.
    pub async fn next_ingest(
        &mut self,
        cache: &mut EvmCache,
    ) -> Result<Option<ReactiveBatchReport<N>>, ReactiveEngineError> {
        self.ensure_subscriber_chain(cache)?;
        if self.pending_checkpoint.is_some() {
            return Err(ReactiveEngineError::PendingCheckpointCommit);
        }
        if self.pending_acknowledgement.is_some() {
            return self.commit_pending_acknowledgement().await.map(Some);
        }
        let batch = self.subscriber.next_batch().await?;
        self.ensure_subscriber_chain(cache)?;
        let Some(mut batch) = batch else {
            return Ok(None);
        };
        let delivery_token = batch.take_delivery_token();
        let report = self.runtime.ingest_batch(cache, batch)?;
        self.stage_or_return_acknowledgement(delivery_token, report)
            .await
    }

    /// Poll the subscriber once and ingest the returned batch with resync
    /// execution — the loop shape for consumers that rely on coverage-gap
    /// repair (root-gate resyncs, handler-requested re-reads).
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] for subscriber/cache chain mismatch,
    /// pending checkpoint state, subscriber polling, runtime ingestion, or
    /// delivery-acknowledgement failure. A failed acknowledgement remains
    /// pending and is retried before polling again.
    pub async fn next_ingest_with_resync(
        &mut self,
        cache: &mut EvmCache,
    ) -> Result<Option<ReactiveBatchReport<N>>, ReactiveEngineError> {
        self.ensure_subscriber_chain(cache)?;
        if self.pending_checkpoint.is_some() {
            return Err(ReactiveEngineError::PendingCheckpointCommit);
        }
        if self.pending_acknowledgement.is_some() {
            return self.commit_pending_acknowledgement().await.map(Some);
        }
        let batch = self.subscriber.next_batch().await?;
        self.ensure_subscriber_chain(cache)?;
        let Some(mut batch) = batch else {
            return Ok(None);
        };
        let delivery_token = batch.take_delivery_token();
        let report = self.runtime.ingest_batch_with_resync(cache, batch)?;
        self.stage_or_return_acknowledgement(delivery_token, report)
            .await
    }

    /// Poll, ingest, atomically checkpoint, then acknowledge one batch.
    ///
    /// The ordering is strict: subscriber acknowledgement is never attempted
    /// until the complete cache checkpoint is synced. If checkpointing or
    /// acknowledgement fails, the in-memory pending commit is retried before
    /// any later batch is polled, so a transient disk failure cannot cause the
    /// already-applied batch to execute twice in the same process. Across a
    /// process restart, [`resume_from_durable_checkpoint`](Self::resume_from_durable_checkpoint)
    /// uses the stored delivery token and delivery witness to recognize and
    /// acknowledge an identical replay without re-ingestion. Reusing a token
    /// for different input or cursor state fails closed. Mutating the cache while
    /// a commit is pending also fails closed rather than binding newer state to
    /// older delivery metadata. Any explicit, implicit, or removed-log reorg
    /// that cannot be proven from the retained effect journal is rejected before
    /// mutation/save/ACK; configure
    /// [`ReactiveConfig::journal_depth`] to cover the subscriber's reorg horizon.
    /// Hooks are dispatched only after checkpoint staging
    /// succeeds, but remain in-process observers rather than a durable outbox;
    /// see [`ReactiveHook`]. The subscriber must advertise
    /// [`SubscriberCapability::DurableReplay`]; ephemeral subscribers are
    /// rejected before polling.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] when the subscriber lacks durable replay,
    /// identities or replay witnesses conflict, a checkpoint/ACK is already in
    /// an incompatible state, polling or ingestion fails, complete rollback
    /// proof is unavailable, the cache changes after staging, persistence
    /// fails, or delivery acknowledgement fails. Pending checkpoint/ACK work is
    /// retained for retry before another poll.
    pub async fn next_ingest_checkpointed(
        &mut self,
        cache: &mut EvmCache,
        store: &DurableCheckpointStore,
        identity: &DurableCheckpointIdentity,
    ) -> Result<Option<CheckpointedIngest<N>>, ReactiveEngineError> {
        if !self.subscriber.capabilities().supports_durable_replay() {
            return Err(ReactiveEngineError::SubscriberNotDurable);
        }
        self.ensure_subscriber_chain(cache)?;
        if self.pending_acknowledgement.is_some() {
            return Err(ReactiveEngineError::PendingAcknowledgementCommit);
        }
        self.ensure_checkpoint_identity(cache, identity)?;
        if self.pending_checkpoint.is_some() {
            return self.commit_pending_checkpoint(cache, store).await.map(Some);
        }

        let batch = self.subscriber.next_batch().await?;
        self.ensure_subscriber_chain(cache)?;
        let Some(mut batch) = batch else {
            return Ok(None);
        };
        if batch_preconfirmation(&batch)?.is_some() {
            return Err(ReactiveEngineError::PreconfirmationNotCheckpointable);
        }
        self.runtime.discard_preconfirmed_branch(cache);
        let delivery_witness = batch
            .delivery_token()
            .map(|_| durable_delivery_witness(&batch))
            .transpose()?;
        let delivery_token = batch.take_delivery_token();
        let subscriber_checkpoint = batch.take_subscriber_checkpoint();
        if let (Some(replay_token), Some(committed_token)) = (
            delivery_token.as_ref(),
            self.last_checkpoint_delivery_token.as_ref(),
        ) && replay_token == committed_token
        {
            let committed_witness = self
                .last_checkpoint_delivery_witness
                .ok_or(ReactiveEngineError::MissingReplayWitness)?;
            if delivery_witness != Some(committed_witness) {
                return Err(ReactiveEngineError::ReplayDeliveryMismatch);
            }
            self.subscriber
                .acknowledge_delivery(replay_token.clone())
                .await
                .map_err(ReactiveEngineError::Acknowledgement)?;
            return Ok(Some(CheckpointedIngest::ReplayAcknowledged));
        }

        self.ensure_checkpointable_reorgs(&batch)?;

        let incoming_block = latest_canonical_batch_block(&batch);
        let cache_state = EvmCacheStateSnapshot::capture(cache);
        let runtime_state = self.runtime.checkpoint_state();
        let report = match self.runtime.ingest_batch_direct(cache, batch) {
            Ok(report) => report,
            Err(error) => {
                cache_state.restore(cache);
                self.runtime.restore_transaction_state(runtime_state);
                return Err(error.into());
            }
        };
        let reports = report.reports.clone();
        let stage = CheckpointStage {
            incoming_block,
            delivery_token,
            delivery_witness,
            subscriber_checkpoint,
            staged_generation: cache.snapshot_generation(),
            report,
        };
        if let Err(error) = self.stage_checkpoint(identity, stage) {
            cache_state.restore(cache);
            self.runtime.restore_transaction_state(runtime_state);
            return Err(error);
        }
        self.runtime.dispatch_reports(&reports);
        self.commit_pending_checkpoint(cache, store).await.map(Some)
    }

    /// Checkpointed counterpart to [`next_ingest_with_resync`](Self::next_ingest_with_resync).
    /// Requires [`SubscriberCapability::DurableReplay`] and rejects an
    /// ephemeral subscriber before polling.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineError`] for the same durability, identity,
    /// rollback-proof, replay-witness, polling, ingestion, persistence,
    /// mutation-fence, and acknowledgement failures as
    /// [`next_ingest_checkpointed`](Self::next_ingest_checkpointed).
    pub async fn next_ingest_with_resync_checkpointed(
        &mut self,
        cache: &mut EvmCache,
        store: &DurableCheckpointStore,
        identity: &DurableCheckpointIdentity,
    ) -> Result<Option<CheckpointedIngest<N>>, ReactiveEngineError> {
        if !self.subscriber.capabilities().supports_durable_replay() {
            return Err(ReactiveEngineError::SubscriberNotDurable);
        }
        self.ensure_subscriber_chain(cache)?;
        if self.pending_acknowledgement.is_some() {
            return Err(ReactiveEngineError::PendingAcknowledgementCommit);
        }
        self.ensure_checkpoint_identity(cache, identity)?;
        if self.pending_checkpoint.is_some() {
            return self.commit_pending_checkpoint(cache, store).await.map(Some);
        }

        let batch = self.subscriber.next_batch().await?;
        self.ensure_subscriber_chain(cache)?;
        let Some(mut batch) = batch else {
            return Ok(None);
        };
        if batch_preconfirmation(&batch)?.is_some() {
            return Err(ReactiveEngineError::PreconfirmationNotCheckpointable);
        }
        self.runtime.discard_preconfirmed_branch(cache);
        let delivery_witness = batch
            .delivery_token()
            .map(|_| durable_delivery_witness(&batch))
            .transpose()?;
        let delivery_token = batch.take_delivery_token();
        let subscriber_checkpoint = batch.take_subscriber_checkpoint();
        if let (Some(replay_token), Some(committed_token)) = (
            delivery_token.as_ref(),
            self.last_checkpoint_delivery_token.as_ref(),
        ) && replay_token == committed_token
        {
            let committed_witness = self
                .last_checkpoint_delivery_witness
                .ok_or(ReactiveEngineError::MissingReplayWitness)?;
            if delivery_witness != Some(committed_witness) {
                return Err(ReactiveEngineError::ReplayDeliveryMismatch);
            }
            self.subscriber
                .acknowledge_delivery(replay_token.clone())
                .await
                .map_err(ReactiveEngineError::Acknowledgement)?;
            return Ok(Some(CheckpointedIngest::ReplayAcknowledged));
        }

        self.ensure_checkpointable_reorgs(&batch)?;

        let incoming_block = latest_canonical_batch_block(&batch);
        let cache_state = EvmCacheStateSnapshot::capture(cache);
        let runtime_state = self.runtime.checkpoint_state();
        let report = match self.runtime.ingest_batch_with_resync_direct(cache, batch) {
            Ok(report) => report,
            Err(error) => {
                cache_state.restore(cache);
                self.runtime.restore_transaction_state(runtime_state);
                return Err(error.into());
            }
        };
        let reports = report.reports.clone();
        let stage = CheckpointStage {
            incoming_block,
            delivery_token,
            delivery_witness,
            subscriber_checkpoint,
            staged_generation: cache.snapshot_generation(),
            report,
        };
        if let Err(error) = self.stage_checkpoint(identity, stage) {
            cache_state.restore(cache);
            self.runtime.restore_transaction_state(runtime_state);
            return Err(error);
        }
        self.runtime.dispatch_reports(&reports);
        self.commit_pending_checkpoint(cache, store).await.map(Some)
    }

    fn stage_checkpoint(
        &mut self,
        identity: &DurableCheckpointIdentity,
        stage: CheckpointStage<N>,
    ) -> Result<(), ReactiveEngineError> {
        let CheckpointStage {
            incoming_block,
            delivery_token,
            delivery_witness,
            subscriber_checkpoint,
            staged_generation,
            report,
        } = stage;
        if delivery_token.is_some() != delivery_witness.is_some() {
            return Err(ReactiveEngineError::DeliveryWitness(
                "delivery token and witness must be staged together".into(),
            ));
        }
        let runtime_checkpoint = self.runtime.durable_checkpoint_bytes()?;
        let block = self
            .runtime
            .last_canonical_block()
            .map(|block| DurableCheckpointBlock {
                number: block.number,
                hash: block.hash,
                parent_hash: block.parent_hash,
                timestamp: block.timestamp,
            })
            .or(incoming_block)
            .or_else(|| self.last_checkpoint_block.clone())
            .ok_or(ReactiveEngineError::MissingCheckpointBlock)?;
        let metadata = DurableCheckpointMetadata {
            identity: identity.clone(),
            block,
            delivery_token: delivery_token
                .as_ref()
                .or(self.last_checkpoint_delivery_token.as_ref())
                .map(|token| token.as_bytes().to_vec()),
            delivery_witness: if delivery_token.is_some() {
                delivery_witness
            } else {
                self.last_checkpoint_delivery_witness
            },
            subscriber_checkpoint: subscriber_checkpoint
                .as_ref()
                .or(self.last_subscriber_checkpoint.as_ref())
                .map(|checkpoint| checkpoint.as_bytes().to_vec()),
            runtime_checkpoint: Some(runtime_checkpoint),
        };
        self.pending_checkpoint = Some(PendingCheckpoint {
            metadata,
            delivery_token,
            report,
            saved_to: None,
            staged_generation,
        });
        Ok(())
    }

    fn ensure_checkpointable_reorgs(
        &self,
        batch: &ReactiveInputBatch<N>,
    ) -> Result<(), ReactiveEngineError> {
        let state = CanonicalSequenceState::new(
            self.runtime
                .journal
                .iter()
                .map(|entry| entry.block)
                .collect(),
            self.runtime.coverage_head,
            self.runtime.safe_head,
            self.runtime.finalized_head,
        );
        match validate_canonical_sequence_internal(
            &state,
            batch,
            CanonicalSequenceValidationPolicy::RequireCompleteRollback,
        ) {
            Ok(_) => Ok(()),
            Err(CanonicalSequenceError::Invalid(error)) => Err(error.into()),
            Err(CanonicalSequenceError::IncompleteRollback {
                common_ancestor,
                oldest_retained,
                ..
            }) => Err(ReactiveEngineError::CheckpointReorgOutsideJournal {
                common_ancestor,
                oldest_journaled: oldest_retained,
                journal_depth: self.runtime.config.journal_depth,
            }),
        }
    }

    async fn stage_or_return_acknowledgement(
        &mut self,
        delivery_token: Option<SubscriberDeliveryToken>,
        report: ReactiveBatchReport<N>,
    ) -> Result<Option<ReactiveBatchReport<N>>, ReactiveEngineError> {
        let Some(token) = delivery_token else {
            return Ok(Some(report));
        };
        self.pending_acknowledgement = Some(PendingAcknowledgement { token, report });
        self.commit_pending_acknowledgement().await.map(Some)
    }

    async fn commit_pending_acknowledgement(
        &mut self,
    ) -> Result<ReactiveBatchReport<N>, ReactiveEngineError> {
        let token = self
            .pending_acknowledgement
            .as_ref()
            .expect("caller checked pending acknowledgement")
            .token
            .clone();
        self.subscriber
            .acknowledge_delivery(token)
            .await
            .map_err(ReactiveEngineError::Acknowledgement)?;
        Ok(self
            .pending_acknowledgement
            .take()
            .expect("pending acknowledgement remains until commit")
            .report)
    }

    async fn commit_pending_checkpoint(
        &mut self,
        cache: &EvmCache,
        store: &DurableCheckpointStore,
    ) -> Result<CheckpointedIngest<N>, ReactiveEngineError> {
        let pending = self
            .pending_checkpoint
            .as_mut()
            .expect("caller checked pending checkpoint");
        let cache_generation = cache.snapshot_generation();
        if cache_generation != pending.staged_generation {
            return Err(ReactiveEngineError::PendingCheckpointCacheChanged {
                staged_generation: pending.staged_generation,
                current_generation: cache_generation,
            });
        }
        if pending.saved_to.as_deref() != Some(store.path()) {
            store
                .save_async(cache, pending.metadata.clone())
                .await
                .map_err(ReactiveEngineError::Checkpoint)?;
            pending.saved_to = Some(store.path().to_path_buf());
        }
        if let Some(token) = pending.delivery_token.clone() {
            self.subscriber
                .acknowledge_delivery(token)
                .await
                .map_err(ReactiveEngineError::Acknowledgement)?;
        }

        let pending = self
            .pending_checkpoint
            .take()
            .expect("pending checkpoint remains until commit");
        self.last_checkpoint_block = Some(pending.metadata.block);
        self.checkpoint_identity = Some(pending.metadata.identity);
        self.last_checkpoint_delivery_token = pending
            .metadata
            .delivery_token
            .map(SubscriberDeliveryToken::new);
        self.last_checkpoint_delivery_witness = pending.metadata.delivery_witness;
        self.last_subscriber_checkpoint = pending
            .metadata
            .subscriber_checkpoint
            .map(SubscriberCheckpoint::new);
        Ok(CheckpointedIngest::Applied(pending.report))
    }

    fn ensure_checkpoint_identity(
        &self,
        cache: &EvmCache,
        identity: &DurableCheckpointIdentity,
    ) -> Result<(), ReactiveEngineError> {
        if identity.chain_id != cache.chain_id() {
            return Err(ReactiveEngineError::Checkpoint(
                DurableCheckpointError::CacheChainMismatch {
                    cache_chain_id: cache.chain_id(),
                    checkpoint_chain_id: identity.chain_id,
                },
            ));
        }
        if let Some(actual) = self.checkpoint_identity.as_ref()
            && actual != identity
        {
            return Err(ReactiveEngineError::Checkpoint(
                DurableCheckpointError::IdentityMismatch {
                    expected: identity.clone(),
                    actual: actual.clone(),
                },
            ));
        }
        if let Some(pending) = self.pending_checkpoint.as_ref()
            && &pending.metadata.identity != identity
        {
            return Err(ReactiveEngineError::Checkpoint(
                DurableCheckpointError::IdentityMismatch {
                    expected: identity.clone(),
                    actual: pending.metadata.identity.clone(),
                },
            ));
        }
        Ok(())
    }
}

fn latest_canonical_batch_block<N: Network>(
    batch: &ReactiveInputBatch<N>,
) -> Option<DurableCheckpointBlock> {
    let record_block = batch
        .records()
        .iter()
        .enumerate()
        .filter(|(index, _)| {
            batch
                .record_delivery_scope(*index)
                .is_some_and(DeliveryScope::advances_canonical_state)
        })
        .filter_map(|(_, record)| canonical_record_block(record))
        .max_by_key(|block| block.number)
        .cloned();
    let control_block = batch
        .chain_controls()
        .iter()
        .filter_map(|control| match control {
            ChainControl::Reorg {
                common_ancestor, ..
            } => Some(common_ancestor),
            ChainControl::Barrier {
                block: Some(block), ..
            }
            | ChainControl::CanonicalProgress(block) => Some(block),
            ChainControl::Safe(_)
            | ChainControl::Finalized(_)
            | ChainControl::Barrier { block: None, .. } => None,
        })
        .max_by_key(|block| block.number)
        .cloned();

    record_block
        .into_iter()
        .chain(control_block)
        .max_by_key(|block| block.number)
        .map(|block| DurableCheckpointBlock {
            number: block.number,
            hash: block.hash,
            parent_hash: block.parent_hash,
            timestamp: block.timestamp,
        })
}

impl<S, N> ReactiveEngine<S, N>
where
    N: Network,
    S: InterestOwnerSubscriber<N>,
{
    /// Register a handler with both the runtime and subscriber, backfilling its
    /// log interests from the runtime's last canonical block.
    ///
    /// This is the continuity-safe default for mid-lifecycle registration. The
    /// subscriber adopts the live desired state first, delivers the new owner's
    /// matching records at retained block `C` as owner catch-up, then delivers
    /// `C + 1` through activation as global canonical catch-up over the complete
    /// handler union. No discovery gap opens, and every effect after `C` enters
    /// the ordinary global rollback journal. On a runtime that has not journaled any canonical block yet
    /// (fresh start, or `journal_depth` 0) registration is live-only, matching
    /// pre-ingestion bootstrap. Use
    /// [`register_handler_with_backfill`](Self::register_handler_with_backfill)
    /// for an explicit replay of one retained block or
    /// [`register_handler_live_only`](Self::register_handler_live_only) to opt
    /// out of backfill entirely.
    ///
    /// Subscriber registration commits before runtime routing is installed. If
    /// the subscriber operation fails or is cancelled, the runtime remains
    /// unchanged.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineRegisterError`] when the handler id is already
    /// registered or the subscriber rejects/does not support the required
    /// owner update or coordinated catch-up.
    pub async fn register_handler(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
    ) -> Result<(), ReactiveEngineRegisterError> {
        let backfill = self
            .runtime
            .last_canonical_block()
            .filter(|retained| {
                self.runtime.journal.iter().any(|entry| {
                    optional_block_refs_are_compatible(Some(&entry.block), Some(retained))
                })
            })
            .map(HandlerRegistrationCatchup::CoordinatedCanonical)
            .unwrap_or(HandlerRegistrationCatchup::LiveOnly);
        self.register_handler_inner(handler, backfill).await
    }

    /// Register a handler and replay its matching logs at one exact retained
    /// canonical block.
    ///
    /// Owner-only effects are appended to that block's existing rollback
    /// journal entry. Consequently this method accepts only a bounded
    /// [`SubscriberBackfill`] whose start, end, and hash-certified retained
    /// anchor all identify the same journaled block. Wider/deeper recovery must
    /// use ordinary global canonical ingestion (for example startup catch-up),
    /// where every handler sees the records and the runtime advances coverage.
    ///
    /// If subscriber registration fails or is cancelled, the runtime remains
    /// unchanged.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineRegisterError`] when the handler id is already
    /// registered, the requested backfill is not exactly one hash-certified
    /// retained journal block, or the subscriber update fails.
    pub async fn register_handler_with_backfill(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
        backfill: SubscriberBackfill,
    ) -> Result<(), ReactiveEngineRegisterError> {
        self.register_handler_inner(handler, HandlerRegistrationCatchup::OwnerBackfill(backfill))
            .await
    }

    /// Register a handler without any log backfill — only logs delivered after
    /// its live subscription starts are routed to it.
    ///
    /// If subscriber registration fails or is cancelled, the runtime remains
    /// unchanged.
    ///
    /// # Errors
    ///
    /// Returns [`ReactiveEngineRegisterError`] when the handler id is already
    /// registered or the subscriber cannot commit the owner update.
    pub async fn register_handler_live_only(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
    ) -> Result<(), ReactiveEngineRegisterError> {
        self.register_handler_inner(handler, HandlerRegistrationCatchup::LiveOnly)
            .await
    }

    async fn register_handler_inner(
        &mut self,
        handler: Arc<dyn ReactiveHandler<N>>,
        catchup: HandlerRegistrationCatchup,
    ) -> Result<(), ReactiveEngineRegisterError> {
        let id = handler.id();
        if self.runtime.contains_handler(&id) {
            return Err(RegisterError::DuplicateHandler(id).into());
        }
        let interests = handler.interests();

        if let HandlerRegistrationCatchup::OwnerBackfill(backfill) = &catchup {
            let retained_anchor = backfill.retained_anchor().copied();
            let is_exact_retained_block = retained_anchor.is_some_and(|anchor| {
                backfill.start_block() == anchor.number
                    && backfill.end_block() == Some(anchor.number)
                    && self.runtime.journal.iter().any(|entry| {
                        optional_block_refs_are_compatible(Some(&entry.block), Some(&anchor))
                    })
            });
            if !is_exact_retained_block {
                return Err(ReactiveEngineRegisterError::BackfillOutsideJournal {
                    start_block: backfill.start_block(),
                    end_block: backfill.end_block(),
                    retained_anchor,
                });
            }
        }

        let subscribed = match catchup {
            HandlerRegistrationCatchup::OwnerBackfill(backfill) => {
                self.subscriber
                    .add_interest_owner_with_backfill(id.clone(), &interests, backfill)
                    .await
            }
            HandlerRegistrationCatchup::CoordinatedCanonical(retained) => {
                self.subscriber
                    .add_interest_owner_with_canonical_catchup(id.clone(), &interests, retained)
                    .await
            }
            HandlerRegistrationCatchup::LiveOnly => {
                self.subscriber
                    .add_interest_owner(id.clone(), &interests)
                    .await
            }
        };
        if let Err(error) = subscribed {
            return Err(error.into());
        }

        // `&mut self` excludes concurrent registry mutation between the
        // duplicate preflight and this commit. Registration is deliberately
        // subscriber-first: cancelling the awaited operation cannot leave a
        // runtime handler active without committed subscriber interests.
        self.runtime
            .registry
            .insert_handler_prepared(id, handler, interests);
        Ok(())
    }

    /// Register every handler currently in the runtime registry as a subscriber
    /// interest owner.
    ///
    /// This is the no-history bootstrap path for a fresh runtime/subscriber pair
    /// before ingestion starts, or for reattaching an already-aligned durable
    /// subscriber whose exact owner state was restored independently. Each
    /// handler becomes its own owner through one exact bulk replacement;
    /// crash-stale owners and unowned/base interests are removed.
    ///
    /// No backfill is requested. It is therefore **not** the restart-recovery path for a new or
    /// potentially stale subscriber after the runtime has processed canonical
    /// state: use
    /// [`sync_handler_interests_with_backfill`](Self::sync_handler_interests_with_backfill),
    /// which exact-replaces the owner set and closes continuity from the
    /// restored runtime position.
    ///
    /// The complete exact set commits through one subscriber operation; an
    /// error or cancellation leaves the previously committed topology
    /// authoritative.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] when the subscriber cannot atomically
    /// replace the complete owner topology.
    pub async fn sync_handler_interests(&mut self) -> Result<(), SubscriberError> {
        let owners = self
            .runtime
            .handler_ids()
            .into_iter()
            .map(|id| {
                let interests = self
                    .runtime
                    .handler_interests(&id)
                    .map(<[ReactiveInterest<N>]>::to_vec)
                    .unwrap_or_default();
                (id, interests)
            })
            .collect();
        self.subscriber.replace_interest_owners(owners).await
    }

    /// Rebuild subscriber owner state from a runtime that already embodies a
    /// canonical checkpoint.
    ///
    /// The runtime registry is authoritative: the subscriber must atomically
    /// replace its complete owner set, removing crash-stale owners as well as
    /// adding the current ones. Log catch-up is routed globally through normal
    /// canonical ingestion and begins strictly at `C + 1`, where
    /// `C` is [`ReactiveRuntime::last_canonical_block`], because the restored
    /// cache already contains every effect through `C`. The exact number/hash
    /// identity of `C` remains attached as a retained baseline and must be
    /// validated by the subscriber before it exposes post-baseline records.
    /// Global routing is essential: startup catch-up effects enter the ordinary
    /// canonical journal and can be rolled back if the certified branch later
    /// reorganizes; owner-only catch-up is reserved for a true mid-lifecycle
    /// handler addition.
    ///
    /// A runtime without a canonical position must use
    /// [`sync_handler_interests`](Self::sync_handler_interests) instead. Block
    /// `u64::MAX` is rejected rather than wrapping or replaying the baseline.
    /// The replacement is one subscriber commit boundary: errors and
    /// cancellation leave the previous topology authoritative.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError::InvalidConfig`] when no canonical baseline
    /// exists or no exclusive successor can be represented, and otherwise
    /// propagates subscriber validation, transport, or atomic-commit failures.
    pub async fn sync_handler_interests_with_backfill(&mut self) -> Result<(), SubscriberError> {
        let baseline =
            self.runtime
                .last_canonical_block()
                .ok_or(SubscriberError::InvalidConfig(
                    "cannot continuity-sync handlers before a canonical runtime position exists",
                ))?;
        let backfill = SubscriberBackfill::after_canonical_block(baseline)?;
        let owners = self
            .runtime
            .handler_ids()
            .into_iter()
            .map(|id| {
                let interests = self
                    .runtime
                    .handler_interests(&id)
                    .map(<[ReactiveInterest<N>]>::to_vec)
                    .unwrap_or_default();
                (id, interests)
            })
            .collect();
        self.subscriber
            .replace_interest_owners_with_global_backfill(owners, backfill)
            .await
    }

    /// Unregister a handler from both the subscriber and runtime.
    ///
    /// Subscriber interests are removed first so no new live records are routed
    /// to a handler after it has left the runtime registry. Returns the removed
    /// handler when the id was registered. If subscriber removal fails or is
    /// cancelled, runtime routing remains installed.
    ///
    /// This is the routing/transport half of dropping an adapter. State the
    /// handler accumulated is deliberately left in place; the complete teardown
    /// for a pool or adapter that will not return is:
    ///
    /// ```text
    /// engine.unregister_handler(&id).await?;
    /// for request_id in handler_request_ids {
    ///     // Drop only this handler generation's queued repair work.
    ///     engine.runtime_mut().cancel_pending_resync(&request_id);
    /// }
    /// for address in exclusively_owned_addresses {
    ///     // Shared accounts require caller-side owner reference counting.
    ///     engine.runtime_mut().untrack_account(address);
    /// }
    /// // optional: evict cached state via StateUpdate::purge / cache purge APIs
    /// ```
    ///
    /// Health, metrics, the reorg journal, hooks, and freshness stamps are
    /// runtime-global and are never touched by handler removal.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] when the subscriber cannot commit owner
    /// removal. In that case runtime routing remains installed.
    pub async fn unregister_handler(
        &mut self,
        id: &HandlerId,
    ) -> Result<Option<Arc<dyn ReactiveHandler<N>>>, SubscriberError> {
        self.subscriber.remove_interest_owner(id).await?;
        Ok(self.runtime.unregister_handler(id))
    }
}

/// Alloy-backed event subscriber.
///
/// The default transport slice drives Alloy pubsub subscriptions for logs,
/// block headers, and pending transaction hashes. The HTTP polling `watch_*`
/// transport remains available behind the opt-in `reactive-polling` feature.
/// Pubsub streams reconnect automatically after termination, and log
/// subscriptions are backfilled from the last seen block. Owner-scoped log
/// additions can request backfill from an explicit block anchor. Full pending
/// transaction hydration and full block bodies remain explicit follow-up work.
///
/// Historical log fetching is deliberately a bounded live-subscriber aid, not
/// a high-volume indexer: each filter/window is issued as one complete-range
/// `eth_getLogs` request. [`SubscriberConfig::max_backfill_log_bytes`] rejects
/// an oversized decoded response, but the subscriber does not adaptively split
/// block ranges and cannot bypass an RPC provider's result cap. Keep owner
/// registration and reconnect windows modest; use an indexing source such as
/// HyperSync behind [`EventSubscriber`] for deep or high-density catch-up.
///
/// With no registered interests, [`EventSubscriber::next_batch`] returns
/// `Ok(None)`.
pub struct AlloySubscriber<P, N: Network = Ethereum> {
    provider: P,
    /// Stable identity for the provider session used by Flashblocks and every
    /// follow-up pending-state read.
    provider_ref: Option<ProviderRef>,
    /// Optional provider dedicated to canonical log-context verification.
    /// Keeping this separate prevents a high-volume pubsub connection from
    /// starving its own verification requests behind log notifications.
    log_verification_provider: Option<P>,
    /// Provider chain identity, resolved once before any record can escape.
    chain_id: Option<u64>,
    mode: SubscriberMode,
    config: SubscriberConfig,
    base_interests: Vec<ReactiveInterest<N>>,
    owned_interests: Vec<OwnedSubscriberInterests<N>>,
    next_owner_epoch: u64,
    interests: Vec<ReactiveInterest<N>>,
    /// Stable source id per distinct provider-facing log filter. Ids key
    /// delivery anchors and live `SubscriberEvent`s; entries are retired (and
    /// their anchors pruned) when no planned stream references the filter, so
    /// long-lived owner churn cannot grow this map unboundedly.
    log_source_ids: HashMap<Filter, usize>,
    next_log_source_id: usize,
    pending_backfills: VecDeque<QueuedSubscriberBackfill>,
    /// Successfully connected sources whose subscribe-then-backfill step has
    /// not committed yet. Installation happens before the backfill await, so a
    /// cancelled reconcile keeps the live stream and retries only the missing
    /// historical window.
    pending_source_backfills: VecDeque<SubscriberStreamSource>,
    /// Set when interest bookkeeping changed since the last successful stream
    /// reconcile, so steady-state polling skips the desired-vs-live diff.
    sources_dirty: bool,
    /// Conservative generation of desired/live stream topology. Successful
    /// owner progress is activatable only against the same clean revision.
    stream_revision: u64,
    state: AlloySubscriberState<N>,
    pending_records: VecDeque<SubscriberInputRecord<N>>,
    pending_chain_controls: VecDeque<ChainControl>,
    /// Owner copies of live records consumed during an in-flight reconcile.
    /// These remain hidden from subscriber output until the owning reconcile
    /// commits and survive cancellation so subscribe-first adoption cannot
    /// lose an event at an await boundary.
    pending_reconcile_owner_records: VecDeque<BufferedSubscriberOwnerRecord<N>>,
    /// Sticky fail-closed capacity error. Once an event could not be retained,
    /// only a full replacement registration can establish a new baseline.
    resource_error: Option<String>,
    last_seen_log_blocks: HashMap<usize, u64>,
    verified_log_blocks: HashMap<(u64, B256), BlockRef>,
    verified_log_block_order: VecDeque<(u64, B256)>,
    recent_input_refs: VecDeque<InputRef>,
    recent_input_ref_set: HashSet<InputRef>,
    recent_owner_input_refs: HashMap<SubscriberOwnerEpoch, VecDeque<InputRef>>,
    recent_owner_input_ref_sets: HashMap<SubscriberOwnerEpoch, HashSet<InputRef>>,
    recent_compat_owner_input_refs: HashMap<HandlerId, VecDeque<InputRef>>,
    recent_compat_owner_input_ref_sets: HashMap<HandlerId, HashSet<InputRef>>,
    base_flashblock_header: Option<(FixedBytes<8>, BaseFlashblockBase)>,
    flashblocks_by_hash: HashMap<B256, FlashblockRef>,
    flashblock_hash_order: VecDeque<B256>,
    unmatched_pending_logs: VecDeque<(usize, Log)>,
    latest_preconfirmation: Option<FlashblockRef>,
    preconfirmed_seen_logs: HashSet<(B256, u64)>,
    _network: PhantomData<N>,
}

struct OwnedSubscriberInterests<N: Network = Ethereum> {
    owner: HandlerId,
    interests: Vec<ReactiveInterest<N>>,
    epoch: Option<SubscriberOwnerEpoch>,
    state: SubscriberOwnerState,
    baseline: Option<BlockRef>,
    progress: Option<SubscriberOwnerProgress>,
    progress_stream_revision: Option<u64>,
}

#[derive(Clone)]
struct SubscriberOwnerReconcilePlan<N: Network = Ethereum> {
    epoch: SubscriberOwnerEpoch,
    interests: Vec<ReactiveInterest<N>>,
    retained: BlockRef,
    from_block: u64,
}

struct SubscriberOwnerCatchup {
    logs: Vec<Log>,
    certified: BlockRef,
}

#[derive(Clone, Copy)]
struct SubscriberOwnerCatchupOptions {
    target_preverified: bool,
    max_logs: usize,
    max_log_bytes: usize,
    max_requests_in_flight: usize,
}

struct SubscriberOwnerReconcileFilter {
    filter: Filter,
    from_block: u64,
}

struct BufferedSubscriberOwnerRecord<N: Network = Ethereum> {
    record: ReactiveInputRecord<N>,
    owners: Vec<SubscriberOwnerEpoch>,
}

const OWNER_RECONCILE_FILTERS_PER_CHUNK: usize = 256;

struct QueuedSubscriberBackfill {
    /// `None` means global canonical catch-up; `Some` is compatibility
    /// owner-only catch-up for true mid-lifecycle additions.
    owner: Option<HandlerId>,
    epoch: Option<SubscriberOwnerEpoch>,
    /// Complete logical filter set for one certified, globally ordered window.
    filters: Vec<Filter>,
    backfill: SubscriberBackfill,
}

/// Best-effort installation of rustls' `ring` crypto provider as the process
/// default, so an `wss://` TLS handshake under `reactive-ws` does not panic with
/// "no process-level CryptoProvider available". Runs at most once and ignores the
/// error if a default provider is already installed (the host app may have set
/// its own).
#[cfg(feature = "reactive-ws")]
fn ensure_ring_crypto_provider() {
    use std::sync::Once;
    static INSTALL: Once = Once::new();
    INSTALL.call_once(|| {
        let _ = rustls::crypto::ring::default_provider().install_default();
    });
}

impl<P, N: Network> AlloySubscriber<P, N> {
    /// Create a new Alloy subscriber.
    pub fn new(provider: P, mode: SubscriberMode, config: SubscriberConfig) -> Self {
        #[cfg(feature = "reactive-ws")]
        ensure_ring_crypto_provider();
        Self {
            provider,
            provider_ref: None,
            log_verification_provider: None,
            chain_id: None,
            mode,
            config,
            base_interests: Vec::new(),
            owned_interests: Vec::new(),
            next_owner_epoch: 0,
            interests: Vec::new(),
            log_source_ids: HashMap::new(),
            next_log_source_id: 0,
            pending_backfills: VecDeque::new(),
            pending_source_backfills: VecDeque::new(),
            sources_dirty: true,
            stream_revision: 0,
            state: AlloySubscriberState::Uninitialized,
            pending_records: VecDeque::new(),
            pending_chain_controls: VecDeque::new(),
            pending_reconcile_owner_records: VecDeque::new(),
            resource_error: None,
            last_seen_log_blocks: HashMap::new(),
            verified_log_blocks: HashMap::new(),
            verified_log_block_order: VecDeque::new(),
            recent_input_refs: VecDeque::new(),
            recent_input_ref_set: HashSet::new(),
            recent_owner_input_refs: HashMap::new(),
            recent_owner_input_ref_sets: HashMap::new(),
            recent_compat_owner_input_refs: HashMap::new(),
            recent_compat_owner_input_ref_sets: HashMap::new(),
            base_flashblock_header: None,
            flashblocks_by_hash: HashMap::new(),
            flashblock_hash_order: VecDeque::new(),
            unmatched_pending_logs: VecDeque::new(),
            latest_preconfirmation: None,
            preconfirmed_seen_logs: HashSet::new(),
            _network: PhantomData,
        }
    }

    /// Borrow the provider.
    pub fn provider(&self) -> &P {
        &self.provider
    }

    /// Bind this subscriber to the concrete provider lease that supplies
    /// Flashblocks. Callers obtain the lease from a transport endpoint marked
    /// with the single `flashblocks = true` flag.
    #[must_use]
    pub fn with_provider_ref(mut self, provider: ProviderRef) -> Self {
        self.provider_ref = Some(provider);
        self
    }

    /// Use a separate provider for canonical log-context verification.
    ///
    /// This is recommended with
    /// [`SubscriberConfig::verify_log_block_context`] in high-volume pubsub
    /// deployments. The provider must target the same chain; every fetched
    /// block is still checked against the log's number, hash, and timestamp.
    #[must_use]
    pub fn with_log_verification_provider(mut self, provider: P) -> Self {
        self.log_verification_provider = Some(provider);
        self
    }

    /// Subscriber mode.
    pub fn mode(&self) -> SubscriberMode {
        self.mode
    }

    /// Subscriber config.
    pub fn config(&self) -> &SubscriberConfig {
        &self.config
    }

    /// Registered interests across base and owner-scoped registrations.
    pub fn registered_interests(&self) -> &[ReactiveInterest<N>] {
        &self.interests
    }

    /// Stage a fresh, epoch-scoped interest owner without making its inputs
    /// canonically routable yet.
    ///
    /// The returned token is required by every later lifecycle operation. A
    /// staged owner participates in provider subscription planning immediately,
    /// while its matching input remains owner-scoped until
    /// [`activate_interest_owner`](Self::activate_interest_owner) succeeds.
    /// Post-block owners require hash-certified
    /// [`reconcile_interest_owner`](Self::reconcile_interest_owner) progress on
    /// the current clean stream revision before activation.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberOwnerError`] for invalid subscriber configuration,
    /// duplicate owners, unsupported post-block interests, unsupported
    /// transport interests, block-number overflow, or epoch exhaustion.
    pub fn stage_interest_owner(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        start: SubscriberOwnerStart,
    ) -> Result<SubscriberOwnerEpoch, SubscriberOwnerError> {
        validate_subscriber_config(&self.config)?;
        if matches!(&start, SubscriberOwnerStart::PostBlock(_))
            && interests
                .iter()
                .any(|interest| !matches!(interest, ReactiveInterest::Logs(_)))
        {
            return Err(SubscriberOwnerError::UnsupportedPostBlockInterest);
        }
        if self
            .owned_interests
            .iter()
            .any(|entry| entry.owner == owner)
        {
            return Err(SubscriberOwnerError::AlreadyRegistered(owner));
        }

        let mut next_owned = self.clone_owned_interests();
        next_owned.push(OwnedSubscriberInterests {
            owner: owner.clone(),
            interests: interests.to_vec(),
            epoch: None,
            state: SubscriberOwnerState::Staged,
            baseline: None,
            progress: None,
            progress_stream_revision: None,
        });
        let next_registered = aggregate_interests(&self.base_interests, &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;

        let baseline = match start {
            SubscriberOwnerStart::Live => None,
            SubscriberOwnerStart::PostBlock(block) => {
                block
                    .number
                    .checked_add(1)
                    .ok_or(SubscriberOwnerError::PostBlockOverflow(block.number))?;
                Some(block)
            }
        };
        let sequence = self
            .next_owner_epoch
            .checked_add(1)
            .ok_or(SubscriberOwnerError::EpochExhausted)?;
        let epoch = SubscriberOwnerEpoch {
            owner: owner.clone(),
            sequence,
        };

        self.next_owner_epoch = sequence;
        let entry = next_owned
            .last_mut()
            .expect("staged owner was appended during preflight");
        entry.epoch = Some(epoch.clone());
        entry.baseline = baseline;
        self.owned_interests = next_owned;
        self.interests = next_registered;
        self.sources_dirty = true;

        Ok(epoch)
    }

    /// Stage replacement interests for one currently active logical owner.
    ///
    /// The active epoch remains canonical while the replacement reconciles.
    /// Commit both epochs atomically with
    /// [`commit_interest_owner_replacement`](Self::commit_interest_owner_replacement),
    /// or abort the staged epoch with [`abort_interest_owner`](Self::abort_interest_owner).
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberOwnerError`] for invalid subscriber configuration,
    /// missing/non-unique active owner state, unsupported post-block interests,
    /// unsupported transport interests, block-number overflow, or epoch
    /// exhaustion.
    pub fn stage_interest_owner_replacement(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        start: SubscriberOwnerStart,
    ) -> Result<SubscriberOwnerEpoch, SubscriberOwnerError> {
        validate_subscriber_config(&self.config)?;
        if matches!(&start, SubscriberOwnerStart::PostBlock(_))
            && interests
                .iter()
                .any(|interest| !matches!(interest, ReactiveInterest::Logs(_)))
        {
            return Err(SubscriberOwnerError::UnsupportedPostBlockInterest);
        }
        let active_count = self
            .owned_interests
            .iter()
            .filter(|entry| {
                entry.owner == owner
                    && entry.state == SubscriberOwnerState::Active
                    && entry.epoch.is_some()
            })
            .count();
        if active_count != 1
            || self
                .owned_interests
                .iter()
                .any(|entry| entry.owner == owner && entry.state != SubscriberOwnerState::Active)
        {
            return Err(SubscriberOwnerError::AlreadyRegistered(owner));
        }

        let mut next_owned = self.clone_owned_interests();
        next_owned.push(OwnedSubscriberInterests {
            owner: owner.clone(),
            interests: interests.to_vec(),
            epoch: None,
            state: SubscriberOwnerState::Staged,
            baseline: None,
            progress: None,
            progress_stream_revision: None,
        });
        let next_registered = aggregate_interests(&self.base_interests, &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;

        let baseline = match start {
            SubscriberOwnerStart::Live => None,
            SubscriberOwnerStart::PostBlock(block) => {
                block
                    .number
                    .checked_add(1)
                    .ok_or(SubscriberOwnerError::PostBlockOverflow(block.number))?;
                Some(block)
            }
        };
        let sequence = self
            .next_owner_epoch
            .checked_add(1)
            .ok_or(SubscriberOwnerError::EpochExhausted)?;
        let epoch = SubscriberOwnerEpoch {
            owner: owner.clone(),
            sequence,
        };

        self.next_owner_epoch = sequence;
        let entry = next_owned
            .last_mut()
            .expect("staged replacement owner was appended during preflight");
        entry.epoch = Some(epoch.clone());
        entry.baseline = baseline;
        self.owned_interests = next_owned;
        self.interests = next_registered;
        self.sources_dirty = true;
        Ok(epoch)
    }

    /// Current transaction state for an exact owner epoch.
    pub fn interest_owner_state(
        &self,
        epoch: &SubscriberOwnerEpoch,
    ) -> Option<SubscriberOwnerState> {
        self.owned_interests
            .iter()
            .find(|entry| entry.epoch.as_ref() == Some(epoch))
            .map(|entry| entry.state)
    }

    /// Latest hash-certified reconcile progress for an exact owner epoch.
    pub fn interest_owner_progress(
        &self,
        epoch: &SubscriberOwnerEpoch,
    ) -> Option<&SubscriberOwnerProgress> {
        self.owned_interests
            .iter()
            .find(|entry| entry.epoch.as_ref() == Some(epoch))
            .and_then(|entry| entry.progress.as_ref())
    }

    /// Make a staged owner canonical after its actor-side installation commits.
    ///
    /// Returns `false` for stale tokens and owners not currently staged.
    pub fn activate_interest_owner(&mut self, epoch: &SubscriberOwnerEpoch) -> bool {
        let stream_revision = self.stream_revision;
        let sources_dirty = self.sources_dirty;
        let Some(entry) = self
            .owned_interests
            .iter_mut()
            .find(|entry| entry.epoch.as_ref() == Some(epoch))
        else {
            return false;
        };
        if entry.state != SubscriberOwnerState::Staged
            || (entry.baseline.is_some()
                && (entry.progress.is_none()
                    || entry.progress_stream_revision != Some(stream_revision)
                    || sources_dirty))
        {
            return false;
        }
        entry.state = SubscriberOwnerState::Active;
        true
    }

    /// Atomically replace one active owner epoch with one reconciled staged epoch.
    pub fn commit_interest_owner_replacement(
        &mut self,
        active: &SubscriberOwnerEpoch,
        replacement: &SubscriberOwnerEpoch,
    ) -> bool {
        let Some(active_index) = self
            .owned_interests
            .iter()
            .position(|entry| entry.epoch.as_ref() == Some(active))
        else {
            return false;
        };
        let Some(replacement_index) = self
            .owned_interests
            .iter()
            .position(|entry| entry.epoch.as_ref() == Some(replacement))
        else {
            return false;
        };
        if active_index == replacement_index
            || active.owner() != replacement.owner()
            || self.owned_interests[active_index].state != SubscriberOwnerState::Active
            || self.owned_interests[replacement_index].state != SubscriberOwnerState::Staged
            || (self.owned_interests[replacement_index].baseline.is_some()
                && (self.owned_interests[replacement_index].progress.is_none()
                    || self.owned_interests[replacement_index].progress_stream_revision
                        != Some(self.stream_revision)
                    || self.sources_dirty))
        {
            return false;
        }

        self.owned_interests[replacement_index].state = SubscriberOwnerState::Active;
        self.owned_interests.remove(active_index);
        self.purge_owner_epoch(active);
        self.rebuild_registered_interests();
        self.retire_unreferenced_filters();
        self.sources_dirty = true;
        true
    }

    /// Prepare an exact active owner for removal without changing desired
    /// interests, streams, anchors, or queued canonical input.
    ///
    /// The caller establishes its delivery fence after this transition. Use
    /// [`abort_interest_owner`](Self::abort_interest_owner) to restore the owner
    /// on actor-side failure, or
    /// [`finalize_interest_owner_removal`](Self::finalize_interest_owner_removal)
    /// once canonical routing has been removed.
    pub fn prepare_interest_owner_removal(&mut self, epoch: &SubscriberOwnerEpoch) -> bool {
        let Some(entry) = self
            .owned_interests
            .iter_mut()
            .find(|entry| entry.epoch.as_ref() == Some(epoch))
        else {
            return false;
        };
        if entry.state != SubscriberOwnerState::Active {
            return false;
        }
        entry.state = SubscriberOwnerState::Removing;
        true
    }

    /// Finalize a previously prepared exact owner removal.
    ///
    /// Returns the removed interests, or `None` for stale tokens and owners not
    /// currently in [`SubscriberOwnerState::Removing`]. Repeating finalization
    /// is therefore idempotent.
    pub fn finalize_interest_owner_removal(
        &mut self,
        epoch: &SubscriberOwnerEpoch,
    ) -> Option<Vec<ReactiveInterest<N>>> {
        let index = self.owned_interests.iter().position(|entry| {
            entry.epoch.as_ref() == Some(epoch) && entry.state == SubscriberOwnerState::Removing
        })?;
        let removed = self.owned_interests.remove(index).interests;
        self.purge_owner_epoch(epoch);
        self.rebuild_registered_interests();
        self.retire_unreferenced_filters();
        self.sources_dirty = true;
        Some(removed)
    }

    /// Abort an epoch-scoped owner lifecycle operation.
    ///
    /// A staged owner is removed completely. A prepared removal is restored to
    /// active. Active and unknown epochs are unchanged. Repeating the same
    /// abort is therefore safe and returns `false` after the first effect.
    pub fn abort_interest_owner(&mut self, epoch: &SubscriberOwnerEpoch) -> bool {
        let Some(index) = self
            .owned_interests
            .iter()
            .position(|entry| entry.epoch.as_ref() == Some(epoch))
        else {
            return false;
        };
        match self.owned_interests[index].state {
            SubscriberOwnerState::Staged => {
                self.owned_interests.remove(index);
                self.purge_owner_epoch(epoch);
                self.rebuild_registered_interests();
                self.retire_unreferenced_filters();
                self.sources_dirty = true;
                true
            }
            SubscriberOwnerState::Removing => {
                self.owned_interests[index].state = SubscriberOwnerState::Active;
                true
            }
            SubscriberOwnerState::Active => false,
        }
    }

    fn purge_owner_epoch(&mut self, epoch: &SubscriberOwnerEpoch) {
        self.pending_backfills
            .retain(|backfill| backfill.epoch.as_ref() != Some(epoch));
        self.pending_records
            .retain_mut(|pending| match &mut pending.scope {
                SubscriberInputScope::Canonical { owners }
                | SubscriberInputScope::CanonicalResidual { owners, .. } => {
                    owners.retain(|owner| owner != epoch);
                    true
                }
                SubscriberInputScope::OwnerOnly { owners } => {
                    owners.retain(|owner| owner != epoch);
                    !owners.is_empty()
                }
                SubscriberInputScope::OwnerOnlyHandlers { .. }
                | SubscriberInputScope::Preconfirmed => true,
            });
        self.pending_reconcile_owner_records.retain_mut(|pending| {
            pending.owners.retain(|owner| owner != epoch);
            !pending.owners.is_empty()
        });
        self.recent_owner_input_refs.remove(epoch);
        self.recent_owner_input_ref_sets.remove(epoch);
    }

    /// Atomically add or replace several owners while preserving unrelated ones.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, duplicate owners,
    /// mixed lifecycle APIs, unsupported interests, or backfill-capacity
    /// exhaustion. No owner state changes on error.
    pub fn upsert_interest_owners(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> Result<(), SubscriberError> {
        self.upsert_interest_owners_inner(owners, None)
    }

    /// Atomically add or replace several owners and queue one common backfill
    /// policy for every log interest while preserving unrelated owners.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, duplicate owners,
    /// mixed lifecycle APIs, unsupported interests, or backfill-capacity
    /// exhaustion. No owner or backfill state changes on error.
    pub fn upsert_interest_owners_with_backfill(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        backfill: SubscriberBackfill,
    ) -> Result<(), SubscriberError> {
        self.upsert_interest_owners_inner(owners, Some(backfill))
    }

    fn upsert_interest_owners_inner(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        explicit_backfill: Option<SubscriberBackfill>,
    ) -> Result<(), SubscriberError> {
        validate_subscriber_config(&self.config)?;
        let mut seen = HashSet::with_capacity(owners.len());
        let mut next_owned = self.clone_owned_interests();
        for (owner, interests) in &owners {
            if !seen.insert(owner.clone()) {
                return Err(SubscriberError::InvalidConfig(
                    "bulk owner upsert contains a duplicate owner",
                ));
            }
            if self
                .owned_interests
                .iter()
                .any(|entry| &entry.owner == owner && entry.epoch.is_some())
            {
                return Err(SubscriberError::InvalidConfig(
                    "cannot mix compatibility and epoch-scoped owner lifecycle APIs",
                ));
            }
            if let Some(entry) = next_owned.iter_mut().find(|entry| &entry.owner == owner) {
                entry.interests = interests.clone();
                entry.state = SubscriberOwnerState::Active;
                entry.baseline = None;
                entry.progress = None;
                entry.progress_stream_revision = None;
            } else {
                next_owned.push(OwnedSubscriberInterests {
                    owner: owner.clone(),
                    interests: interests.clone(),
                    epoch: None,
                    state: SubscriberOwnerState::Active,
                    baseline: None,
                    progress: None,
                    progress_stream_revision: None,
                });
            }
        }
        let next_registered = aggregate_interests(&self.base_interests, &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;

        // Build every owner's replacement queue before the first mutation.
        // Besides keeping capacity failure atomic, this preserves continuity
        // for changed filter shapes when the caller did not provide a common
        // open-ended backfill that already covers the old delivery anchor.
        let mut replacement_backfills = Vec::new();
        for (owner, interests) in &owners {
            let previous_filters: Vec<Filter> = self
                .owner_interests(owner)
                .map(log_filters)
                .unwrap_or_default();
            let continuity_anchor = previous_filters
                .iter()
                .filter_map(|filter| self.log_anchor(filter))
                .min();
            let filters = log_filters(interests);
            if let Some(backfill) = explicit_backfill
                && !filters.is_empty()
            {
                replacement_backfills.push(QueuedSubscriberBackfill {
                    owner: Some(owner.clone()),
                    epoch: None,
                    filters: filters.clone(),
                    backfill,
                });
            }
            let explicit_covers = explicit_backfill.is_some_and(|explicit| {
                explicit.end_block().is_none()
                    && continuity_anchor.is_some_and(|anchor| explicit.start_block() <= anchor)
            });
            let continuity_filters: Vec<_> = filters
                .into_iter()
                .filter(|filter| !previous_filters.contains(filter))
                .collect();
            if let Some(anchor) = continuity_anchor
                && !continuity_filters.is_empty()
                && !explicit_covers
            {
                replacement_backfills.push(QueuedSubscriberBackfill {
                    owner: Some(owner.clone()),
                    epoch: None,
                    filters: continuity_filters,
                    backfill: SubscriberBackfill::from_block(anchor),
                });
            }
        }

        let retained_backfills = self
            .pending_backfills
            .iter()
            .filter(|queued| {
                queued
                    .owner
                    .as_ref()
                    .is_none_or(|owner| !seen.contains(owner))
            })
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        let replacement_units = replacement_backfills
            .iter()
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        if retained_backfills.saturating_add(replacement_units) > self.config.max_pending_backfills
        {
            return Err(SubscriberError::ResourceExhausted(format!(
                "bulk owner update would queue more than {} lazy backfills",
                self.config.max_pending_backfills
            )));
        }

        // All validation and capacity checks are complete. The remaining
        // assignments have no failure or cancellation point, so topology and
        // historical work become authoritative as one local commit.
        self.owned_interests = next_owned;
        self.interests = next_registered;
        for owner in &seen {
            self.recent_compat_owner_input_refs.remove(owner);
            self.recent_compat_owner_input_ref_sets.remove(owner);
        }
        self.retire_unreferenced_filters();
        self.sources_dirty = true;
        self.pending_backfills.retain(|queued| {
            queued
                .owner
                .as_ref()
                .is_none_or(|owner| !seen.contains(owner))
        });
        self.pending_backfills.extend(replacement_backfills);
        Ok(())
    }

    /// Atomically replace every compatibility owner without requesting
    /// historical delivery.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, duplicate owners,
    /// mixed lifecycle APIs, unsupported interests, or resource exhaustion.
    /// The previous topology remains authoritative on error.
    pub fn replace_interest_owners(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> Result<(), SubscriberError> {
        self.replace_interest_owners_inner(owners, None)
    }

    /// Atomically replace every compatibility owner and queue one global
    /// post-baseline backfill for the resulting union of log interests.
    ///
    /// Base interests are replaced. Epoch-scoped lifecycle operations cannot
    /// be mixed with this compatibility replacement because silently deleting
    /// an in-flight epoch would violate its activation transaction.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, duplicate owners,
    /// mixed lifecycle APIs, unsupported interests, or backfill-capacity
    /// exhaustion. The previous topology remains authoritative on error.
    pub fn replace_interest_owners_with_global_backfill(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        backfill: SubscriberBackfill,
    ) -> Result<(), SubscriberError> {
        self.replace_interest_owners_inner(owners, Some(backfill))
    }

    fn replace_interest_owners_inner(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        backfill: Option<SubscriberBackfill>,
    ) -> Result<(), SubscriberError> {
        validate_subscriber_config(&self.config)?;
        if self
            .owned_interests
            .iter()
            .any(|entry| entry.epoch.is_some())
        {
            return Err(SubscriberError::InvalidConfig(
                "cannot replace compatibility owners while an epoch-scoped lifecycle exists",
            ));
        }

        let mut seen = HashSet::with_capacity(owners.len());
        let mut next_owned = Vec::with_capacity(owners.len());
        for (owner, interests) in owners {
            if !seen.insert(owner.clone()) {
                return Err(SubscriberError::InvalidConfig(
                    "owner replacement contains a duplicate owner",
                ));
            }
            next_owned.push(OwnedSubscriberInterests {
                owner,
                interests,
                epoch: None,
                state: SubscriberOwnerState::Active,
                baseline: None,
                progress: None,
                progress_stream_revision: None,
            });
        }
        let next_registered = aggregate_interests(&[], &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;
        let mut filters = log_filters(&next_registered);
        let mut unique_filters = Vec::with_capacity(filters.len());
        for filter in filters.drain(..) {
            if !unique_filters.contains(&filter) {
                unique_filters.push(filter);
            }
        }
        let replacement_backfills: VecDeque<_> = match backfill {
            Some(backfill) if !unique_filters.is_empty() => {
                VecDeque::from([QueuedSubscriberBackfill {
                    owner: None,
                    epoch: None,
                    filters: unique_filters,
                    backfill,
                }])
            }
            Some(_) | None => VecDeque::new(),
        };
        let replacement_units = replacement_backfills
            .iter()
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        if replacement_units > self.config.max_pending_backfills {
            return Err(SubscriberError::ResourceExhausted(format!(
                "owner replacement would queue more than {} lazy backfills",
                self.config.max_pending_backfills
            )));
        }

        // No fallible work remains. The post-baseline range reconstructs every
        // delivery after the cache snapshot, so reset all stale delivery and
        // dedupe state from the prior topology before publishing the exact
        // replacement plus its global historical work.
        self.base_interests.clear();
        self.owned_interests = next_owned;
        self.interests = next_registered;
        self.reset_delivery_state();
        self.pending_backfills = replacement_backfills;
        self.state = AlloySubscriberState::Uninitialized;
        Ok(())
    }

    /// Add or replace the interests owned by `owner`.
    ///
    /// This preserves unrelated owners, queued/pending records, recent dedupe
    /// state, and last-seen log anchors. The live transport is reconciled on the
    /// next [`EventSubscriber::next_batch`] call so newly added log filters can
    /// be subscribed without rebuilding the whole subscriber object.
    ///
    /// Replacing an existing owner is continuity-safe: filters the owner
    /// already had keep their delivery anchors, and any changed or new filter
    /// shape is automatically backfilled from the owner's oldest prior anchor —
    /// growing a pool set on an established owner does not open a delivery gap
    /// for what the old subscription had already covered. A brand-new owner has
    /// no anchor to inherit; pass an explicit
    /// [`add_interest_owner_with_backfill`](Self::add_interest_owner_with_backfill)
    /// anchor (or register through [`ReactiveEngine::register_handler`], which
    /// anchors to the runtime's last canonical block).
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, incompatible
    /// lifecycle state, unsupported interests, or continuity-backfill capacity
    /// exhaustion. The prior owner state remains authoritative on error.
    pub fn add_interest_owner(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
    ) -> Result<(), SubscriberError> {
        self.set_interest_owner(owner, interests, None)
    }

    /// Add or replace owner interests and schedule log backfill for that owner.
    ///
    /// Backfill is queued only for log interests; block and pending transaction
    /// interests are live-only. Queued records can be delivered immediately;
    /// the subsequent provider stream is then caught up from the seeded
    /// delivery anchor, and overlap is deduplicated — so the discovery boundary
    /// is closed end to end as long
    /// as `backfill` starts at (or before) the block the interest was
    /// discovered in. Continuity backfill for a replaced owner (see
    /// [`add_interest_owner`](Self::add_interest_owner)) is queued in addition,
    /// unless this explicit backfill is open-ended and already starts at or
    /// below the owner's prior anchor.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, incompatible
    /// lifecycle state, unsupported interests, or backfill-capacity exhaustion.
    /// The prior owner state remains authoritative on error.
    pub fn add_interest_owner_with_backfill(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        backfill: SubscriberBackfill,
    ) -> Result<(), SubscriberError> {
        self.set_interest_owner(owner, interests, Some(backfill))
    }

    /// Add or replace one owner at retained canonical block `C`, then queue the
    /// coordinated cutover required by [`ReactiveEngine::register_handler`].
    ///
    /// The new owner alone receives matching records from `C` so its effects
    /// attach to the runtime's existing journal entry. Every matching log from
    /// `C + 1` through the activation head is then delivered canonically over
    /// the complete interest union. [`Self::next_scoped_batch`] installs the
    /// desired live streams before draining either window, closing the
    /// subscribe/backfill gap. Alloy cannot reconstruct historical block or
    /// pending-transaction deliveries through this log backfill path, so a
    /// mixed interest topology is rejected rather than silently underfilled.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] for invalid configuration, incompatible
    /// lifecycle state, unsupported non-log catch-up, block-number overflow, or
    /// resource exhaustion. The prior owner state remains authoritative on
    /// error.
    pub fn add_interest_owner_with_canonical_catchup(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        retained: BlockRef,
    ) -> Result<(), SubscriberError> {
        validate_subscriber_config(&self.config)?;
        if self
            .owned_interests
            .iter()
            .any(|entry| entry.owner == owner && entry.epoch.is_some())
        {
            return Err(SubscriberError::InvalidConfig(
                "cannot mix compatibility and epoch-scoped owner lifecycle APIs",
            ));
        }

        let mut next_owned = self.clone_owned_interests();
        if let Some(entry) = next_owned.iter_mut().find(|entry| entry.owner == owner) {
            entry.interests = interests.to_vec();
            entry.state = SubscriberOwnerState::Active;
            entry.baseline = None;
            entry.progress = None;
            entry.progress_stream_revision = None;
            entry.epoch = None;
        } else {
            next_owned.push(OwnedSubscriberInterests {
                owner: owner.clone(),
                interests: interests.to_vec(),
                epoch: None,
                state: SubscriberOwnerState::Active,
                baseline: None,
                progress: None,
                progress_stream_revision: None,
            });
        }
        let next_registered = aggregate_interests(&self.base_interests, &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;
        if next_registered
            .iter()
            .any(|interest| !matches!(interest, ReactiveInterest::Logs(_)))
        {
            return Err(SubscriberError::Unsupported(
                "Alloy coordinated registration supports log-only interest topologies",
            ));
        }

        let mut owner_filters = Vec::new();
        for filter in log_filters(interests) {
            if !owner_filters.contains(&filter) {
                owner_filters.push(filter);
            }
        }
        let mut global_filters = Vec::new();
        for filter in log_filters(&next_registered) {
            if !global_filters.contains(&filter) {
                global_filters.push(filter);
            }
        }
        let owner_backfill =
            SubscriberBackfill::from_canonical_block_through(retained, retained.number)?;
        let global_backfill = SubscriberBackfill::after_canonical_block(retained)?;
        let replacement_units = owner_filters.len().saturating_add(global_filters.len());
        let retained_units = self
            .pending_backfills
            .iter()
            .filter(|queued| queued.owner.as_ref() != Some(&owner))
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        if retained_units.saturating_add(replacement_units) > self.config.max_pending_backfills {
            return Err(SubscriberError::ResourceExhausted(format!(
                "coordinated owner registration would queue more than {} lazy backfills",
                self.config.max_pending_backfills
            )));
        }

        let mut replacement_backfills = VecDeque::new();
        if !owner_filters.is_empty() {
            replacement_backfills.push_back(QueuedSubscriberBackfill {
                owner: Some(owner.clone()),
                epoch: None,
                filters: owner_filters,
                backfill: owner_backfill,
            });
        }
        // Keep the global certification job even for an empty filter union: it
        // advances canonical coverage through a zero-event registration window.
        replacement_backfills.push_back(QueuedSubscriberBackfill {
            owner: None,
            epoch: None,
            filters: global_filters,
            backfill: global_backfill,
        });

        // Every fallible preflight is complete. Publish topology and both
        // ordered windows as one synchronous local commit.
        self.owned_interests = next_owned;
        self.interests = next_registered;
        self.recent_compat_owner_input_refs.remove(&owner);
        self.recent_compat_owner_input_ref_sets.remove(&owner);
        self.pending_backfills
            .retain(|queued| queued.owner.as_ref() != Some(&owner));
        self.pending_backfills.extend(replacement_backfills);
        self.retire_unreferenced_filters();
        self.sources_dirty = true;
        Ok(())
    }

    /// Remove one owner's interests, preserving unrelated owner/base interests.
    ///
    /// The owner's queued backfills are dropped, and source-id/anchor
    /// bookkeeping for filters no other owner references is retired. Live
    /// streams for retired filters are torn down on the next
    /// [`EventSubscriber::next_batch`] call (dropping an Alloy subscription
    /// unsubscribes provider-side); events already in flight from them stop
    /// matching the merged interest set and are discarded.
    pub fn remove_interest_owner(&mut self, owner: &HandlerId) -> Option<Vec<ReactiveInterest<N>>> {
        let index = self
            .owned_interests
            .iter()
            .position(|entry| &entry.owner == owner && entry.epoch.is_none())?;
        let removed = self.owned_interests.remove(index);
        if let Some(epoch) = &removed.epoch {
            self.purge_owner_epoch(epoch);
        } else {
            self.pending_backfills
                .retain(|backfill| backfill.owner.as_ref() != Some(owner));
            self.recent_compat_owner_input_refs.remove(owner);
            self.recent_compat_owner_input_ref_sets.remove(owner);
        }
        self.rebuild_registered_interests();
        self.retire_unreferenced_filters();
        self.sources_dirty = true;
        Some(removed.interests)
    }

    /// Borrow the interests currently owned by `owner`.
    pub fn owner_interests(&self, owner: &HandlerId) -> Option<&[ReactiveInterest<N>]> {
        self.owned_interests
            .iter()
            .find(|entry| &entry.owner == owner)
            .map(|entry| entry.interests.as_slice())
    }

    fn set_interest_owner(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        backfill: Option<SubscriberBackfill>,
    ) -> Result<(), SubscriberError> {
        validate_subscriber_config(&self.config)?;
        if self
            .owned_interests
            .iter()
            .any(|entry| entry.owner == owner && entry.epoch.is_some())
        {
            return Err(SubscriberError::InvalidConfig(
                "cannot mix compatibility and epoch-scoped owner lifecycle APIs",
            ));
        }

        let mut next_owned = self.clone_owned_interests();
        let replaced_epoch = match next_owned.iter_mut().find(|entry| entry.owner == owner) {
            Some(entry) => {
                entry.interests = interests.to_vec();
                entry.state = SubscriberOwnerState::Active;
                entry.baseline = None;
                entry.progress = None;
                entry.progress_stream_revision = None;
                entry.epoch.take()
            }
            None => {
                next_owned.push(OwnedSubscriberInterests {
                    owner: owner.clone(),
                    interests: interests.to_vec(),
                    epoch: None,
                    state: SubscriberOwnerState::Active,
                    baseline: None,
                    progress: None,
                    progress_stream_revision: None,
                });
                None
            }
        };
        let next_registered = aggregate_interests(&self.base_interests, &next_owned);
        validate_supported_interests(self.mode, &self.config, &next_registered)?;

        // Continuity capture, before the mutation lands: the owner's previous
        // filter shapes and the oldest delivery anchor among them. A changed
        // filter gets a fresh source id with no anchor, so without this
        // hand-off, replacing an owner's interests (the normal way to grow a
        // pool set) would silently discard the delivery watermark and open a
        // gap until some later explicit backfill.
        let previous_filters: Vec<Filter> = self
            .owner_interests(&owner)
            .map(log_filters)
            .unwrap_or_default();
        let continuity_anchor: Option<u64> = previous_filters
            .iter()
            .filter_map(|filter| self.log_anchor(filter))
            .min();

        // Build the replacement queue before committing owner state. Capacity
        // failure is therefore atomic and cannot leave desired interests ahead
        // of the historical work required to make them continuous.
        let mut replacement_backfills = Vec::new();
        let filters = log_filters(interests);
        if let Some(backfill) = backfill
            && !filters.is_empty()
        {
            replacement_backfills.push(QueuedSubscriberBackfill {
                owner: Some(owner.clone()),
                epoch: None,
                filters: filters.clone(),
                backfill,
            });
        }
        let explicit_covers = backfill.is_some_and(|explicit| {
            explicit.end_block().is_none()
                && continuity_anchor.is_some_and(|anchor| explicit.start_block() <= anchor)
        });
        let continuity_filters: Vec<_> = filters
            .into_iter()
            .filter(|filter| !previous_filters.contains(filter))
            .collect();
        if let Some(anchor) = continuity_anchor
            && !continuity_filters.is_empty()
            && !explicit_covers
        {
            replacement_backfills.push(QueuedSubscriberBackfill {
                owner: Some(owner.clone()),
                epoch: None,
                filters: continuity_filters,
                backfill: SubscriberBackfill::from_block(anchor),
            });
        }
        let retained_backfills = self
            .pending_backfills
            .iter()
            .filter(|queued| queued.owner.as_ref() != Some(&owner))
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        let replacement_units = replacement_backfills
            .iter()
            .map(|queued| queued.filters.len())
            .sum::<usize>();
        if retained_backfills.saturating_add(replacement_units) > self.config.max_pending_backfills
        {
            return Err(SubscriberError::ResourceExhausted(format!(
                "owner update would queue more than {} lazy backfills",
                self.config.max_pending_backfills
            )));
        }

        self.owned_interests = next_owned;
        self.interests = next_registered;
        if let Some(epoch) = replaced_epoch {
            self.purge_owner_epoch(&epoch);
        } else {
            self.recent_compat_owner_input_refs.remove(&owner);
            self.recent_compat_owner_input_ref_sets.remove(&owner);
        }
        self.retire_unreferenced_filters();
        self.sources_dirty = true;

        // Re-queue this owner's backfills from scratch: previously queued
        // entries may reference filter shapes that no longer exist.
        self.pending_backfills
            .retain(|queued| queued.owner.as_ref() != Some(&owner));
        self.pending_backfills.extend(replacement_backfills);
        Ok(())
    }

    fn clone_owned_interests(&self) -> Vec<OwnedSubscriberInterests<N>> {
        self.owned_interests
            .iter()
            .map(|entry| OwnedSubscriberInterests {
                owner: entry.owner.clone(),
                interests: entry.interests.clone(),
                epoch: entry.epoch.clone(),
                state: entry.state,
                baseline: entry.baseline,
                progress: entry.progress.clone(),
                progress_stream_revision: entry.progress_stream_revision,
            })
            .collect()
    }

    fn rebuild_registered_interests(&mut self) {
        self.interests = aggregate_interests(&self.base_interests, &self.owned_interests);
    }

    /// Delivery anchor (last block known fully delivered) for `filter`, if the
    /// filter has a source id and has seen delivery.
    fn log_anchor(&self, filter: &Filter) -> Option<u64> {
        if let Some(anchor) = self
            .log_source_ids
            .get(filter)
            .and_then(|id| self.last_seen_log_blocks.get(id))
        {
            return Some(*anchor);
        }

        // Logical owner filters may be represented by a broader provider
        // stream after fan-in. Its oldest live watermark is a conservative
        // continuity anchor: it can cause extra backfill, never a missed log.
        self.log_source_ids
            .values()
            .filter_map(|id| self.last_seen_log_blocks.get(id).copied())
            .min()
    }

    /// Every logical log filter across base and owner interests, merged within
    /// each origin and deduplicated across origins. These shapes remain the
    /// exact routing and owner-continuity boundary; provider subscriptions may
    /// fan several of them into one broader filter.
    // `Filter` derives `Hash`/`Eq` and has no interior mutability; the
    // `mutable_key_type` lint is a known false positive for it.
    #[allow(clippy::mutable_key_type)]
    fn logical_log_filters(&self) -> Vec<Filter> {
        let mut filters = log_filters(&self.base_interests);
        for entry in &self.owned_interests {
            filters.extend(log_filters(&entry.interests));
        }
        let mut seen = HashSet::new();
        filters.retain(|filter| seen.insert(filter.clone()));
        filters
    }

    /// Provider-facing log filters. Compatible logical filters fan into a
    /// small number of address/topic supersets, then split only when the
    /// configured address ceiling requires it. Exact matching remains local in
    /// `enqueue_event`, so this reduces subscriptions without broadening owner
    /// delivery.
    fn log_stream_filters(&self) -> Vec<Filter> {
        let mut merged = Vec::new();
        for filter in self.logical_log_filters() {
            merge_log_subscription_filter(&mut merged, &filter);
        }

        let max_addresses = self.config.max_log_addresses_per_subscription.max(1);
        let mut planned = Vec::new();
        for filter in merged {
            let mut addresses: Vec<_> = filter.address.iter().copied().collect();
            if addresses.len() <= max_addresses {
                planned.push(filter);
                continue;
            }
            addresses.sort_unstable();
            for chunk in addresses.chunks(max_addresses) {
                let mut split = filter.clone();
                split.address = FilterSet::default();
                for address in chunk {
                    split.address.insert(*address);
                }
                planned.push(split);
            }
        }
        planned
    }

    /// Drop source-id and anchor bookkeeping for filters no longer referenced
    /// by any base or owner interest, so long-lived owner churn cannot grow the
    /// maps unboundedly. Live streams for retired filters are pruned by the
    /// next reconcile.
    // `Filter` derives `Hash`/`Eq` and has no interior mutability; the
    // `mutable_key_type` lint is a known false positive for it.
    #[allow(clippy::mutable_key_type)]
    fn retire_unreferenced_filters(&mut self) {
        let mut live: HashSet<Filter> = self.log_stream_filters().into_iter().collect();
        if let AlloySubscriberState::Active(streams) = &self.state {
            for entry in &streams.entries {
                match &entry.source {
                    SubscriberStreamSource::PubSubLog { filter, .. }
                    | SubscriberStreamSource::BasePendingLog { filter, .. }
                    | SubscriberStreamSource::PollingLog { filter } => {
                        live.insert(filter.clone());
                    }
                    SubscriberStreamSource::BaseFlashblocks
                    | SubscriberStreamSource::OpPendingFlashblocks
                    | SubscriberStreamSource::PubSubPendingHashes
                    | SubscriberStreamSource::PubSubBlockHeaders
                    | SubscriberStreamSource::PollingPendingHashes => {}
                }
            }
        }
        self.log_source_ids
            .retain(|filter, _| live.contains(filter));
        let live_ids: HashSet<usize> = self.log_source_ids.values().copied().collect();
        self.last_seen_log_blocks
            .retain(|id, _| live_ids.contains(id));
    }

    fn drain_next_scoped_batch(&mut self) -> Option<SubscriberInputBatch<N>> {
        if self.pending_records.is_empty() && self.pending_chain_controls.is_empty() {
            return None;
        }

        let first_preconfirmation = self.pending_records.front().and_then(|record| {
            if record.scope != SubscriberInputScope::Preconfirmed {
                return None;
            }
            match &record.record.context.chain_status {
                ChainStatus::Preconfirmed { flashblock } => Some(flashblock.clone()),
                _ => None,
            }
        });
        let len = self
            .pending_records
            .iter()
            .take(self.config.max_batch_size)
            .take_while(|record| match &first_preconfirmation {
                Some(expected) => {
                    record.scope == SubscriberInputScope::Preconfirmed
                        && matches!(
                            &record.record.context.chain_status,
                            ChainStatus::Preconfirmed { flashblock } if flashblock == expected
                        )
                }
                None => record.scope != SubscriberInputScope::Preconfirmed,
            })
            .count();
        let records = self.pending_records.drain(..len).collect();
        let chain_controls = if first_preconfirmation.is_none() && self.pending_records.is_empty() {
            self.pending_chain_controls.drain(..).collect()
        } else {
            Vec::new()
        };
        Some(SubscriberInputBatch {
            records,
            chain_id: self.chain_id,
            chain_controls,
        })
    }

    fn reset_delivery_state(&mut self) {
        self.pending_records.clear();
        self.pending_chain_controls.clear();
        self.pending_reconcile_owner_records.clear();
        self.resource_error = None;
        self.last_seen_log_blocks.clear();
        self.verified_log_blocks.clear();
        self.verified_log_block_order.clear();
        self.recent_input_refs.clear();
        self.recent_input_ref_set.clear();
        self.recent_owner_input_refs.clear();
        self.recent_owner_input_ref_sets.clear();
        self.recent_compat_owner_input_refs.clear();
        self.recent_compat_owner_input_ref_sets.clear();
        self.pending_backfills.clear();
        self.pending_source_backfills.clear();
        self.log_source_ids.clear();
        self.next_log_source_id = 0;
        self.sources_dirty = true;
        self.reset_flashblock_tracking();
    }

    fn reset_flashblock_tracking(&mut self) {
        self.base_flashblock_header = None;
        self.flashblocks_by_hash.clear();
        self.flashblock_hash_order.clear();
        self.unmatched_pending_logs.clear();
        self.latest_preconfirmation = None;
        self.preconfirmed_seen_logs.clear();
    }

    fn bump_stream_revision(&mut self) {
        self.stream_revision = self.stream_revision.saturating_add(1);
    }
}

impl<P, N> InterestOwnerSubscriber<N> for AlloySubscriber<P, N>
where
    P: Provider<N> + Send + Sync,
    N: Network + 'static,
    N::HeaderResponse: Send + 'static,
{
    fn upsert_interest_owners(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async move {
            if !owners.is_empty() {
                self.ensure_chain_id().await?;
            }
            AlloySubscriber::upsert_interest_owners(self, owners)
        })
    }

    fn replace_interest_owners(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async move {
            if owners.iter().any(|(_, interests)| !interests.is_empty()) {
                self.ensure_chain_id().await?;
            }
            AlloySubscriber::replace_interest_owners(self, owners)
        })
    }

    fn replace_interest_owners_with_global_backfill(
        &mut self,
        owners: Vec<(HandlerId, Vec<ReactiveInterest<N>>)>,
        backfill: SubscriberBackfill,
    ) -> SubscriberOperation<'_, ()> {
        Box::pin(async move {
            if owners.iter().any(|(_, interests)| !interests.is_empty()) {
                self.ensure_chain_id().await?;
            }
            AlloySubscriber::replace_interest_owners_with_global_backfill(self, owners, backfill)
        })
    }

    fn add_interest_owner(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
    ) -> SubscriberOperation<'_, ()> {
        let interests = interests.to_vec();
        Box::pin(async move {
            if !interests.is_empty() {
                self.ensure_chain_id().await?;
            }
            AlloySubscriber::add_interest_owner(self, owner, &interests)
        })
    }

    fn add_interest_owner_with_backfill(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        backfill: SubscriberBackfill,
    ) -> SubscriberOperation<'_, ()> {
        let interests = interests.to_vec();
        Box::pin(async move {
            if !interests.is_empty() {
                self.ensure_chain_id().await?;
            }
            AlloySubscriber::add_interest_owner_with_backfill(self, owner, &interests, backfill)
        })
    }

    fn add_interest_owner_with_canonical_catchup(
        &mut self,
        owner: HandlerId,
        interests: &[ReactiveInterest<N>],
        retained: BlockRef,
    ) -> SubscriberOperation<'_, ()> {
        let interests = interests.to_vec();
        Box::pin(async move {
            // Resolve provider identity before the synchronous topology commit;
            // cancellation or failure at this await leaves prior state intact.
            self.ensure_chain_id().await?;
            AlloySubscriber::add_interest_owner_with_canonical_catchup(
                self, owner, &interests, retained,
            )
        })
    }

    fn remove_interest_owner(
        &mut self,
        owner: &HandlerId,
    ) -> SubscriberOperation<'_, Option<Vec<ReactiveInterest<N>>>> {
        let owner = owner.clone();
        Box::pin(async move { Ok(AlloySubscriber::remove_interest_owner(self, &owner)) })
    }

    fn owner_interests(&self, owner: &HandlerId) -> Option<&[ReactiveInterest<N>]> {
        AlloySubscriber::owner_interests(self, owner)
    }
}

enum AlloySubscriberState<N: Network> {
    Uninitialized,
    Active(SubscriberStreams<N>),
    Empty,
}

struct SubscriberStreams<N: Network> {
    entries: Vec<SubscriberStreamEntry<N>>,
    next_index: usize,
}

struct SubscriberStreamEntry<N: Network> {
    source: SubscriberStreamSource,
    stream: BoxStream<'static, SubscriberEvent<N>>,
}

impl<N: Network> SubscriberStreams<N> {
    fn new() -> Self {
        Self {
            entries: Vec::new(),
            next_index: 0,
        }
    }

    fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    fn push(
        &mut self,
        source: SubscriberStreamSource,
        stream: BoxStream<'static, SubscriberEvent<N>>,
    ) {
        self.entries.push(SubscriberStreamEntry { source, stream });
    }

    #[cfg(test)]
    fn len(&self) -> usize {
        self.entries.len()
    }

    fn contains_source(&self, source: &SubscriberStreamSource) -> bool {
        self.entries
            .iter()
            .any(|entry| entry.source.same_key(source))
    }

    fn retain_sources(&mut self, sources: &[SubscriberStreamSource]) {
        self.entries
            .retain(|entry| sources.iter().any(|source| entry.source.same_key(source)));
        self.normalize_next_index();
    }

    fn normalize_next_index(&mut self) {
        if self.entries.is_empty() {
            self.next_index = 0;
        } else if self.next_index >= self.entries.len() {
            self.next_index %= self.entries.len();
        }
    }

    async fn next(&mut self) -> Option<SubscriberEvent<N>> {
        poll_fn(|cx| {
            self.normalize_next_index();
            if self.entries.is_empty() {
                return std::task::Poll::Ready(None);
            }

            let mut index = self.next_index;
            let mut checked = 0usize;
            while checked < self.entries.len() {
                if index >= self.entries.len() {
                    index = 0;
                }
                match self.entries[index].stream.as_mut().poll_next(cx) {
                    std::task::Poll::Ready(Some(event)) => {
                        if matches!(event, SubscriberEvent::StreamTerminated(_)) {
                            self.entries.remove(index);
                            self.next_index = if self.entries.is_empty() {
                                0
                            } else {
                                index % self.entries.len()
                            };
                        } else {
                            self.next_index = (index + 1) % self.entries.len();
                        }
                        return std::task::Poll::Ready(Some(event));
                    }
                    std::task::Poll::Ready(None) => {
                        self.entries.remove(index);
                        if self.entries.is_empty() {
                            self.next_index = 0;
                            return std::task::Poll::Ready(None);
                        }
                    }
                    std::task::Poll::Pending => {
                        checked += 1;
                        index += 1;
                    }
                }
            }

            if self.entries.is_empty() {
                std::task::Poll::Ready(None)
            } else {
                self.next_index = index % self.entries.len();
                std::task::Poll::Pending
            }
        })
        .await
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[allow(dead_code)]
enum SubscriberTransport {
    PubSub,
    Polling,
}

#[derive(Clone, Debug)]
enum SubscriberStreamSource {
    PubSubLog { id: usize, filter: Filter },
    BasePendingLog { id: usize, filter: Filter },
    BaseFlashblocks,
    OpPendingFlashblocks,
    PubSubPendingHashes,
    PubSubBlockHeaders,
    PollingLog { filter: Filter },
    PollingPendingHashes,
}

impl SubscriberStreamSource {
    fn label(&self) -> &'static str {
        match self {
            Self::PubSubLog { .. } => "pubsub log",
            Self::BasePendingLog { .. } => "Base pendingLogs",
            Self::BaseFlashblocks => "Base newFlashblocks",
            Self::OpPendingFlashblocks => "OP pending Flashblocks",
            Self::PubSubPendingHashes => "pubsub pending transaction hash",
            Self::PubSubBlockHeaders => "pubsub block header",
            Self::PollingLog { .. } => "polling log",
            Self::PollingPendingHashes => "polling pending transaction hash",
        }
    }

    fn is_pubsub(&self) -> bool {
        matches!(
            self,
            Self::PubSubLog { .. }
                | Self::BasePendingLog { .. }
                | Self::BaseFlashblocks
                | Self::PubSubPendingHashes
                | Self::PubSubBlockHeaders
        )
    }

    fn is_flashblocks(&self) -> bool {
        matches!(
            self,
            Self::BasePendingLog { .. } | Self::BaseFlashblocks | Self::OpPendingFlashblocks
        )
    }

    fn same_key(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::PubSubLog { filter: left, .. }, Self::PubSubLog { filter: right, .. })
            | (
                Self::BasePendingLog { filter: left, .. },
                Self::BasePendingLog { filter: right, .. },
            )
            | (Self::PollingLog { filter: left }, Self::PollingLog { filter: right }) => {
                left == right
            }
            (Self::BaseFlashblocks, Self::BaseFlashblocks)
            | (Self::OpPendingFlashblocks, Self::OpPendingFlashblocks)
            | (Self::PubSubPendingHashes, Self::PubSubPendingHashes)
            | (Self::PubSubBlockHeaders, Self::PubSubBlockHeaders)
            | (Self::PollingPendingHashes, Self::PollingPendingHashes) => true,
            _ => false,
        }
    }
}

#[allow(dead_code)]
enum SubscriberEvent<N: Network> {
    Log {
        source_id: usize,
        log: Log,
    },
    BackfilledLogs {
        source_id: usize,
        logs: Vec<Log>,
    },
    Logs(Vec<Log>),
    BlockHeader(N::HeaderResponse),
    PendingHash(B256),
    PendingHashes(Vec<B256>),
    BasePendingLog {
        source_id: usize,
        log: Log,
    },
    BaseFlashblock(BaseFlashblockWirePayload),
    OpFlashblockTick,
    PreconfirmedLogs {
        flashblock: FlashblockRef,
        logs: Vec<Log>,
    },
    FlashblockObserved,
    StreamTerminated(SubscriberStreamSource),
}

impl<P, N> EventSubscriber<N> for AlloySubscriber<P, N>
where
    P: Provider<N> + Send + Sync,
    N: Network + 'static,
    N::HeaderResponse: Send + 'static,
{
    fn chain_id(&self) -> Option<u64> {
        self.chain_id
    }

    fn capabilities(&self) -> SubscriberCapabilities {
        let Ok(transport) = resolve_subscriber_transport(self.mode) else {
            return SubscriberCapabilities::default();
        };
        let mut capabilities = vec![
            SubscriberCapability::Logs,
            SubscriberCapability::PendingTransactionHashes,
            SubscriberCapability::HistoricalBackfill,
            SubscriberCapability::Live,
            SubscriberCapability::OwnerScopedDelivery,
            SubscriberCapability::DynamicInterests,
        ];
        if transport == SubscriberTransport::PubSub {
            capabilities.push(SubscriberCapability::BlockHeaders);
        }
        if self.config.preconfirmations != PreconfirmationMode::Disabled
            && self.provider_ref.is_some()
            && self.chain_id.and_then(flashblocks_adapter).is_some()
        {
            capabilities.push(SubscriberCapability::Preconfirmations);
        }
        SubscriberCapabilities::new(capabilities)
    }

    fn register_interests(
        &mut self,
        interests: &[ReactiveInterest<N>],
    ) -> SubscriberOperation<'_, ()> {
        let interests = interests.to_vec();
        Box::pin(async move {
            validate_subscriber_config(&self.config)?;
            validate_supported_interests(self.mode, &self.config, &interests)?;
            if !interests.is_empty() {
                self.ensure_chain_id().await?;
            }
            self.validate_flashblocks_setup()?;

            self.base_interests = interests;
            self.owned_interests.clear();
            self.rebuild_registered_interests();
            self.reset_delivery_state();
            self.state = AlloySubscriberState::Uninitialized;
            Ok(())
        })
    }

    fn next_batch(&mut self) -> SubscriberNextBatch<'_, N> {
        Box::pin(async {
            Ok(self
                .next_scoped_batch()
                .await?
                .map(SubscriberInputBatch::into_reactive_batch))
        })
    }
}

impl<P, N> AlloySubscriber<P, N>
where
    P: Provider<N> + Send + Sync,
    N: Network + 'static,
    N::HeaderResponse: Send + 'static,
{
    /// Resolve the provider's chain identity once. The assignment happens only
    /// after a complete RPC response, so cancelling the future leaves the
    /// subscriber cleanly retryable.
    async fn ensure_chain_id(&mut self) -> Result<u64, SubscriberError> {
        if let Some(chain_id) = self.chain_id {
            return Ok(chain_id);
        }
        let chain_id = self.provider.get_chain_id().await.map_err(provider_error)?;
        self.chain_id = Some(chain_id);
        Ok(chain_id)
    }

    fn validate_flashblocks_setup(&self) -> Result<(), SubscriberError> {
        if self.config.preconfirmations == PreconfirmationMode::Disabled {
            return Ok(());
        }
        if self.provider_ref.is_none() {
            return Err(SubscriberError::InvalidConfig(
                "Flashblocks require a stable provider ref from a pinned provider lease",
            ));
        }
        let Some(chain_id) = self.chain_id else {
            return Ok(());
        };
        match flashblocks_adapter(chain_id) {
            Some(FlashblocksAdapter::BaseNative)
                if resolve_subscriber_transport(self.mode)? != SubscriberTransport::PubSub
                    && self.config.preconfirmations == PreconfirmationMode::Required =>
            {
                return Err(SubscriberError::Unsupported(
                    "Base Flashblocks require pubsub for newFlashblocks and pendingLogs",
                ));
            }
            Some(_) => {}
            None if self.config.preconfirmations == PreconfirmationMode::Required => {
                return Err(SubscriberError::Unsupported(
                    "Flashblocks are currently implemented for Base and OP chains",
                ));
            }
            None => {}
        }
        Ok(())
    }

    /// Subscribe first, then catch an exact staged owner up through a verified
    /// canonical block.
    ///
    /// This compatibility wrapper delegates to
    /// [`reconcile_interest_owners`](Self::reconcile_interest_owners), so a
    /// driver adopting several owners should call the bulk API once rather than
    /// invoking this method in a loop.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberOwnerError`] when the epoch is not staged, lacks a
    /// baseline, conflicts/regresses, provider certification or transport
    /// fails, returned logs are invalid, or subscriber resources are exhausted.
    pub async fn reconcile_interest_owner(
        &mut self,
        epoch: &SubscriberOwnerEpoch,
        through: BlockRef,
    ) -> Result<SubscriberOwnerProgress, SubscriberOwnerError>
    where
        P: Clone,
    {
        self.reconcile_interest_owners(std::slice::from_ref(epoch), through)
            .await?
            .pop()
            .ok_or(SubscriberOwnerError::NotStaged)
    }

    /// Subscribe first, then atomically catch staged owners up through one
    /// verified canonical block.
    ///
    /// All epochs are preflighted before provider I/O. Live streams are
    /// reconciled once, compatible provider filters are merged into bounded
    /// chunks, and every historical request shares one double target-header
    /// certification. Provider-filter supersets are routed back through each
    /// owner's exact interests, retaining owner-scoped delivery provenance.
    /// Duplicate epoch tokens in `epochs` are coalesced in first-seen order.
    ///
    /// Live events are continuously drained while an independent provider
    /// clone performs catch-up. Fetched owner records and progress become
    /// visible only after every request and the final certification succeed. A
    /// failure leaves every target staged with its prior progress unchanged;
    /// live canonical delivery consumed during the attempt is preserved while
    /// excluding the failed target epochs from its staged-owner audience.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberOwnerError`] when an epoch is not staged, lacks a
    /// baseline, conflicts/regresses, provider certification or transport
    /// fails, returned logs are invalid, or subscriber resources are exhausted.
    /// Target progress remains unchanged on error.
    pub async fn reconcile_interest_owners(
        &mut self,
        epochs: &[SubscriberOwnerEpoch],
        through: BlockRef,
    ) -> Result<Vec<SubscriberOwnerProgress>, SubscriberOwnerError>
    where
        P: Clone,
    {
        if epochs.is_empty() {
            return Ok(Vec::new());
        }

        self.ensure_chain_id().await?;

        let mut seen = HashSet::new();
        let mut plans = Vec::with_capacity(epochs.len());
        for epoch in epochs {
            if !seen.insert(epoch.clone()) {
                continue;
            }
            let entry = self
                .owned_interests
                .iter()
                .find(|entry| {
                    entry.epoch.as_ref() == Some(epoch)
                        && entry.state == SubscriberOwnerState::Staged
                })
                .ok_or(SubscriberOwnerError::NotStaged)?;
            let position = entry
                .progress
                .as_ref()
                .map(|progress| &progress.through)
                .or(entry.baseline.as_ref())
                .ok_or(SubscriberOwnerError::MissingBaseline)?;
            let baseline = position.number;
            if through.number < baseline {
                return Err(SubscriberOwnerError::ProgressRegression {
                    current: baseline,
                    target: through.number,
                });
            }
            let from_block = baseline
                .checked_add(1)
                .ok_or(SubscriberOwnerError::PostBlockOverflow(baseline))?;
            if through.number == baseline && through.hash != position.hash {
                return Err(SubscriberOwnerError::ProgressConflict {
                    number: baseline,
                    current_hash: position.hash,
                    target_hash: through.hash,
                });
            }
            if through.number == from_block
                && through
                    .parent_hash
                    .is_some_and(|parent| parent != position.hash)
            {
                return Err(SubscriberOwnerError::ProgressConflict {
                    number: baseline,
                    current_hash: position.hash,
                    target_hash: through.parent_hash.expect("checked as present above"),
                });
            }
            if entry
                .interests
                .iter()
                .any(|interest| !matches!(interest, ReactiveInterest::Logs(_)))
            {
                return Err(SubscriberOwnerError::UnsupportedPostBlockInterest);
            }
            plans.push(SubscriberOwnerReconcilePlan {
                epoch: epoch.clone(),
                interests: entry.interests.clone(),
                retained: *position,
                from_block,
            });
        }

        // The ordering is intentional and part of the public continuity
        // contract: connect first, then fetch the bounded historical window.
        self.ensure_streams().await?;
        let provider = self.provider.clone();
        let filters = merged_owner_reconcile_filters(&plans, through.number);
        let retained = plans.iter().map(|plan| plan.retained).collect();
        let target_epochs: HashSet<_> = plans.iter().map(|plan| plan.epoch.clone()).collect();
        let fetch = fetch_owner_catchup::<P, N>(
            provider,
            filters,
            retained,
            through,
            SubscriberOwnerCatchupOptions {
                target_preverified: false,
                max_logs: self.config.max_pending_records,
                max_log_bytes: self.config.max_backfill_log_bytes,
                max_requests_in_flight: self.config.max_reconcile_requests_in_flight,
            },
        );
        let SubscriberOwnerCatchup { logs, certified } =
            self.drive_reconcile_fetch(fetch, &target_epochs).await?;

        let records = logs
            .into_iter()
            .map(|log| log_input_record(log, InputSource::Backfill))
            .collect();
        let mut routed_records = Vec::new();
        for record in dedupe_records(sort_records(records)).map_err(|error| {
            SubscriberError::InvalidBackfill(format!(
                "conflicting duplicate owner catch-up record: {error}"
            ))
        })? {
            let block_number = match &record.input {
                ReactiveInput::Log(log) => log
                    .block_number
                    .expect("bulk catch-up logs were validated before commit"),
                _ => unreachable!("bulk owner catch-up contains log records only"),
            };
            let owners: Vec<SubscriberOwnerEpoch> = plans
                .iter()
                .filter(|plan| block_number >= plan.from_block)
                .filter(|plan| {
                    plan.interests
                        .iter()
                        .any(|interest| interest_matches(interest, &record.input))
                })
                .map(|plan| plan.epoch.clone())
                .collect();
            if !owners.is_empty() {
                routed_records.push((record, owners));
            }
        }
        self.ensure_pending_record_capacity(
            routed_records.len(),
            "owner reconciliation historical records",
        )?;

        // Nothing provider-derived becomes authoritative until every record is
        // known to fit. In particular, preserve queued retry state and owner
        // progress when the bounded delivery queue cannot accept the catch-up.
        self.pending_backfills.retain(|queued| {
            queued
                .epoch
                .as_ref()
                .is_none_or(|epoch| !target_epochs.contains(epoch))
        });
        for (record, owners) in routed_records {
            self.enqueue_owner_record_for_owners_unmerged(record, owners);
        }
        self.promote_reconcile_owner_records(&target_epochs);
        self.seed_reconciled_filter_anchors(&plans, certified.number);

        let stream_revision = self.stream_revision;
        let mut progress = Vec::with_capacity(plans.len());
        for plan in plans {
            let item = SubscriberOwnerProgress {
                owner: plan.epoch.clone(),
                through: certified,
            };
            let entry = self
                .owned_interests
                .iter_mut()
                .find(|entry| entry.epoch.as_ref() == Some(&plan.epoch))
                .expect("bulk reconcile holds exclusive access after epoch preflight");
            entry.progress = Some(item.clone());
            entry.progress_stream_revision = Some(stream_revision);
            progress.push(item);
        }
        Ok(progress)
    }

    async fn drive_reconcile_fetch<T, F>(
        &mut self,
        fetch: F,
        target_epochs: &HashSet<SubscriberOwnerEpoch>,
    ) -> Result<T, SubscriberOwnerError>
    where
        F: Future<Output = Result<T, SubscriberOwnerError>>,
    {
        if !matches!(&self.state, AlloySubscriberState::Active(_)) {
            return fetch.await;
        }
        let mut fetch = Box::pin(fetch);
        loop {
            let event = {
                let live = Box::pin(self.next_event());
                match select(fetch, live).await {
                    Either::Left((result, pending_live)) => {
                        drop(pending_live);
                        return result;
                    }
                    Either::Right((event, pending_fetch)) => {
                        fetch = pending_fetch;
                        event
                    }
                }
            };
            let event = event?.ok_or_else(|| {
                SubscriberError::Provider(
                    "Alloy subscriber streams ended during owner reconcile".to_owned(),
                )
            })?;
            self.buffer_reconcile_event_for_owners(&event, target_epochs);
            self.enqueue_event_excluding_owners(event, target_epochs);
            self.check_resource_error()?;
        }
    }

    /// Poll one driver control future with priority over the next scoped batch.
    ///
    /// This is the supported control-interleaving primitive for a subscriber
    /// driver. `control` is borrowed rather than consumed, so a batch win leaves
    /// the caller's pending control future alive. When control wins, the
    /// in-progress subscriber poll is cancelled at a documented safe boundary:
    /// queued records are removed only when a complete batch is returned,
    /// successful backfill steps are committed before the next await, provider
    /// streams created but not installed are dropped, and installed streams
    /// remain owned by the subscriber for the next call.
    ///
    /// The control future is polled first. Therefore a ready shutdown/removal
    /// command cannot starve behind a continuously ready subscriber queue.
    ///
    /// # Errors
    ///
    /// Returns [`SubscriberError`] when the subscriber poll encounters a
    /// transport, continuity, decoding, configuration, or resource failure.
    pub async fn next_scoped_batch_or<C, F>(
        &mut self,
        control: Pin<&mut F>,
    ) -> Result<SubscriberDriverPoll<C, N>, SubscriberError>
    where
        C: Send,
        F: Future<Output = C> + Send,
    {
        let batch = self.next_scoped_batch();
        match select(control, batch).await {
            Either::Left((control, pending_batch)) => {
                drop(pending_batch);
                Ok(SubscriberDriverPoll::Control(control))
            }
            Either::Right((batch, _pending_control)) => batch.map(SubscriberDriverPoll::Batch),
        }
    }

    /// Return the next subscriber batch while retaining staged-owner delivery
    /// provenance captured at enqueue time.
    ///
    /// Transaction-aware drivers must use this method. The compatibility
    /// [`EventSubscriber::next_batch`] method flattens the same queue and keeps
    /// its historical behavior for existing callers.
    ///
    /// For command interleaving, prefer
    /// [`next_scoped_batch_or`](Self::next_scoped_batch_or), which preserves the
    /// cancellation-safety invariants of this poll and prioritizes ready control.
    pub fn next_scoped_batch(&mut self) -> SubscriberNextScopedBatch<'_, N> {
        Box::pin(async {
            self.check_resource_error()?;
            if self.chain_id.is_none()
                && (!self.pending_records.is_empty()
                    || !self.pending_chain_controls.is_empty()
                    || !self.pending_backfills.is_empty()
                    || !self.interests.is_empty())
            {
                self.ensure_chain_id().await?;
            }
            if let Some(batch) = self.drain_next_scoped_batch() {
                return Ok(Some(batch));
            }

            // Subscribe/adopt the complete desired topology before resolving
            // any queued historical upper bound. Live streams therefore own
            // every event that can arrive while the bounded backfill is in
            // flight, including the coordinated registration window.
            self.ensure_streams().await?;
            self.check_resource_error()?;
            if let Some(batch) = self.drain_next_scoped_batch() {
                return Ok(Some(batch));
            }

            self.drain_pending_backfills().await?;
            self.check_resource_error()?;
            if let Some(batch) = self.drain_next_scoped_batch() {
                return Ok(Some(batch));
            }

            if self.interests.is_empty() {
                return Ok(None);
            }

            loop {
                let Some(event) = self.next_event().await? else {
                    return Ok(None);
                };

                self.enqueue_event(event);
                self.check_resource_error()?;
                if let Some(batch) = self.drain_next_scoped_batch() {
                    return Ok(Some(batch));
                }
            }
        })
    }

    /// Bring live streams in line with the current interest set.
    ///
    /// Runs incrementally: the desired-vs-live diff only happens when interest
    /// bookkeeping changed since the last successful pass (`sources_dirty`), so
    /// steady-state polling costs nothing here. Missing sources are connected,
    /// sources for retired filters are dropped (dropping an Alloy subscription
    /// unsubscribes provider-side), and unrelated live streams — with their
    /// delivery and anchor state — are left untouched.
    ///
    /// A newly connected log source whose filter already has a delivery anchor
    /// is caught up from that anchor immediately after subscribing (the same
    /// subscribe-then-backfill order the reconnect path uses). Together with
    /// anchor seeding in [`Self::drain_pending_backfills`], that closes the
    /// window between an adoption backfill and live stream start.
    async fn ensure_streams(&mut self) -> Result<(), SubscriberError> {
        if !self.sources_dirty {
            return Ok(());
        }
        // An interest-less subscriber never touches the provider
        // ([`EventSubscriber::next_batch`] returns `Ok(None)`). Still certify
        // the empty desired topology as clean so a deliberately empty staged
        // epoch can reconcile and activate instead of remaining dirty forever.
        if matches!(self.state, AlloySubscriberState::Uninitialized) && self.interests.is_empty() {
            self.bump_stream_revision();
            self.sources_dirty = false;
            return Ok(());
        }

        let desired = self.stream_sources()?;
        let missing: Vec<SubscriberStreamSource> = match &self.state {
            AlloySubscriberState::Active(streams) => desired
                .iter()
                .filter(|source| !streams.contains_source(source))
                .cloned()
                .collect(),
            AlloySubscriberState::Uninitialized | AlloySubscriberState::Empty => desired.clone(),
        };

        for source in missing {
            let stream = self.connect_source_stream(source.clone()).await?;
            // Publish each successful connection before any later await. If a
            // second connection or anchored catch-up fails/cancels, this stream
            // remains live and the next reconcile skips reconnecting it.
            self.install_source_stream(source.clone(), stream);
            if self.source_requires_backfill(&source) {
                self.queue_source_backfill(source);
            }
        }

        while let Some(source) = self.pending_source_backfills.front().cloned() {
            let desired_and_live = desired.iter().any(|item| item.same_key(&source))
                && matches!(
                    &self.state,
                    AlloySubscriberState::Active(streams) if streams.contains_source(&source)
                );
            if !desired_and_live {
                self.pending_source_backfills.pop_front();
                continue;
            }

            // Anchored catch-up for a source with a known delivery watermark
            // (seeded by a drained adoption backfill, or inherited from a
            // filter shape that was live before): subscribe first, then fetch
            // the gap, so nothing lands between the two. Pop only after the
            // request succeeds; errors and cancellation retain retry intent.
            let event = self.backfill_reconnected_source(&source).await?;
            self.pending_source_backfills.pop_front();
            if let Some(event) = event {
                self.enqueue_event(event);
            }
        }

        if let AlloySubscriberState::Active(streams) = &mut self.state {
            streams.retain_sources(&desired);
            if streams.is_empty() {
                self.state = AlloySubscriberState::Empty;
            }
        }

        self.bump_stream_revision();
        self.sources_dirty = false;
        self.retire_unreferenced_filters();
        Ok(())
    }

    fn install_source_stream(
        &mut self,
        source: SubscriberStreamSource,
        stream: BoxStream<'static, SubscriberEvent<N>>,
    ) {
        match &mut self.state {
            AlloySubscriberState::Active(streams) => {
                if streams.contains_source(&source) {
                    return;
                }
                streams.push(source, stream);
            }
            AlloySubscriberState::Uninitialized | AlloySubscriberState::Empty => {
                let mut streams = SubscriberStreams::new();
                streams.push(source, stream);
                self.state = AlloySubscriberState::Active(streams);
            }
        }
        // A partially completed reconcile is still a topology change. Advance
        // the revision now rather than only at the final clean boundary.
        self.bump_stream_revision();
    }

    fn source_requires_backfill(&self, source: &SubscriberStreamSource) -> bool {
        matches!(source, SubscriberStreamSource::PubSubLog { id, .. }
            if self.last_seen_log_blocks.contains_key(id))
    }

    fn queue_source_backfill(&mut self, source: SubscriberStreamSource) {
        if !self
            .pending_source_backfills
            .iter()
            .any(|pending| pending.same_key(&source))
        {
            self.pending_source_backfills.push_back(source);
        }
    }

    /// Fetch queued adoption/continuity backfills, oldest first.
    ///
    /// An entry is consumed only after its `get_logs` fetch succeeds — a
    /// transient RPC failure surfaces the error and leaves the entry queued for
    /// the next poll, so a flaky request cannot silently discard the missed
    /// window the backfill exists to close. Open-ended backfills resolve their
    /// upper bound to the provider's current head before fetching, and every
    /// drained backfill advances the filter's delivery anchor to that bound —
    /// even a zero-log window — so the filter is reconnect-protected from then
    /// on. Draining pauses as soon as records are ready for delivery; remaining
    /// entries stay queued.
    async fn drain_pending_backfills(&mut self) -> Result<(), SubscriberError> {
        while let Some(queued) = self.pending_backfills.front() {
            // Owner was removed while its backfill was queued.
            let epoch = queued.epoch.clone();
            let owner = queued.owner.clone();
            let owner_exists = match (&epoch, &owner) {
                (Some(epoch), _) => self.interest_owner_state(epoch).is_some(),
                (None, Some(owner)) => self.owner_interests(owner).is_some(),
                (None, None) => true,
            };
            if !owner_exists {
                self.pending_backfills.pop_front();
                continue;
            }
            let filters = queued.filters.clone();
            let backfill = queued.backfill;

            let to_block = match backfill.end_block() {
                Some(to_block) => to_block,
                None => self
                    .provider
                    .get_block_number()
                    .await
                    .map_err(provider_error)?,
            };
            if to_block < backfill.start_block() {
                // An exclusive post-baseline range can be empty when the
                // provider is still exactly at the retained head. Consume the
                // work only after validating that head and seed the filter at
                // the proven baseline so reconnect catch-up starts at C + 1.
                let certified = if let Some(retained) = backfill.retained_anchor() {
                    let actual =
                        fetch_provider_block_ref::<P, N>(&self.provider, retained.number).await?;
                    if !block_ref_satisfies_expected(&actual, retained) {
                        return Err(SubscriberError::InvalidBackfill(format!(
                            "retained anchor {}:{:?} conflicts with provider block {}:{:?}",
                            retained.number, retained.hash, actual.number, actual.hash
                        )));
                    }
                    if to_block < retained.number {
                        return Err(SubscriberError::InvalidBackfill(format!(
                            "backfill upper bound {to_block} precedes retained anchor {}",
                            retained.number
                        )));
                    }
                    Some(actual)
                } else {
                    None
                };
                self.pending_backfills.pop_front();
                for filter in &filters {
                    let source_id = self.log_source_id(filter);
                    if let Some(certified) = certified {
                        self.last_seen_log_blocks
                            .entry(source_id)
                            .and_modify(|anchor| *anchor = (*anchor).max(certified.number))
                            .or_insert(certified.number);
                    }
                }
                if owner.is_none()
                    && let Some(certified) = certified
                {
                    self.pending_chain_controls
                        .push_back(global_backfill_barrier(backfill, certified));
                }
                if !self.pending_chain_controls.is_empty() {
                    break;
                }
                continue;
            }

            let through = fetch_provider_block_ref::<P, N>(&self.provider, to_block).await?;
            let request_filters =
                merged_lazy_backfill_filters(&filters, backfill.start_block(), through.number);
            let retained = backfill.retained_anchor().copied().into_iter().collect();
            let SubscriberOwnerCatchup {
                mut logs,
                certified,
            } = fetch_owner_catchup::<&P, N>(
                &self.provider,
                request_filters,
                retained,
                through,
                SubscriberOwnerCatchupOptions {
                    target_preverified: true,
                    max_logs: self.config.max_pending_records,
                    max_log_bytes: self.config.max_backfill_log_bytes,
                    max_requests_in_flight: self.config.max_reconcile_requests_in_flight,
                },
            )
            .await
            .map_err(lazy_backfill_error)?;
            logs.sort_by_key(|log| {
                (
                    log.block_number.unwrap_or_default(),
                    log.transaction_index.unwrap_or_default(),
                    log.log_index.unwrap_or_default(),
                )
            });
            logs.dedup();
            self.ensure_pending_record_capacity(logs.len(), "lazy subscriber backfill records")?;

            // Fetch succeeded: consume the entry, deliver, and advance the
            // complete filter group through one globally ordered window.
            self.pending_backfills.pop_front();
            if let Some(epoch) = epoch.as_ref() {
                self.enqueue_backfilled_logs(logs, None, Some(epoch), Some(backfill));
            } else if let Some(owner) = owner.as_ref() {
                self.enqueue_compat_owner_backfilled_logs(logs, owner, backfill);
            } else {
                self.enqueue_backfilled_logs(logs, None, None, Some(backfill));
                self.pending_chain_controls
                    .push_back(global_backfill_barrier(backfill, certified));
            }
            for filter in &filters {
                let source_id = self.log_source_id(filter);
                let anchor = self
                    .last_seen_log_blocks
                    .entry(source_id)
                    .or_insert(certified.number);
                *anchor = (*anchor).max(certified.number);
            }

            if !self.pending_records.is_empty() || !self.pending_chain_controls.is_empty() {
                break;
            }
        }
        Ok(())
    }

    fn stream_sources(&mut self) -> Result<Vec<SubscriberStreamSource>, SubscriberError> {
        match resolve_subscriber_transport(self.mode)? {
            SubscriberTransport::PubSub => Ok(self.pubsub_stream_sources()),
            SubscriberTransport::Polling => Ok(self.polling_stream_sources()),
        }
    }

    fn pubsub_stream_sources(&mut self) -> Vec<SubscriberStreamSource> {
        let mut sources = Vec::new();
        let inherited_anchor = self.last_seen_log_blocks.values().copied().min();

        for filter in self.log_stream_filters() {
            let id = self.log_source_id(&filter);
            if let Some(anchor) = inherited_anchor {
                self.last_seen_log_blocks.entry(id).or_insert(anchor);
            }
            sources.push(SubscriberStreamSource::PubSubLog { id, filter });
        }

        if needs_pending_hash_stream(&self.interests) {
            sources.push(SubscriberStreamSource::PubSubPendingHashes);
        }

        if needs_header_block_stream(&self.interests) {
            sources.push(SubscriberStreamSource::PubSubBlockHeaders);
        }

        if self.config.preconfirmations != PreconfirmationMode::Disabled {
            match self.chain_id.and_then(flashblocks_adapter) {
                Some(FlashblocksAdapter::BaseNative) => {
                    sources.push(SubscriberStreamSource::BaseFlashblocks);
                    for filter in self.log_stream_filters() {
                        let id = self.log_source_id(&filter);
                        sources.push(SubscriberStreamSource::BasePendingLog { id, filter });
                    }
                }
                Some(FlashblocksAdapter::OpPending) => {
                    sources.push(SubscriberStreamSource::OpPendingFlashblocks);
                }
                None => {}
            }
        }

        sources
    }

    fn polling_stream_sources(&self) -> Vec<SubscriberStreamSource> {
        let mut sources = Vec::new();

        for filter in self.log_stream_filters() {
            sources.push(SubscriberStreamSource::PollingLog { filter });
        }

        if needs_pending_hash_stream(&self.interests) {
            sources.push(SubscriberStreamSource::PollingPendingHashes);
        }

        if self.config.preconfirmations != PreconfirmationMode::Disabled
            && self.chain_id.and_then(flashblocks_adapter) == Some(FlashblocksAdapter::OpPending)
        {
            sources.push(SubscriberStreamSource::OpPendingFlashblocks);
        }

        sources
    }

    fn log_source_id(&mut self, filter: &Filter) -> usize {
        if let Some(id) = self.log_source_ids.get(filter) {
            return *id;
        }

        let id = self.next_log_source_id;
        self.next_log_source_id = self.next_log_source_id.saturating_add(1);
        self.log_source_ids.insert(filter.clone(), id);
        id
    }

    async fn connect_source_stream(
        &mut self,
        source: SubscriberStreamSource,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        match source {
            SubscriberStreamSource::PubSubLog { id, filter } => {
                self.connect_pubsub_log_stream(id, filter).await
            }
            SubscriberStreamSource::BasePendingLog { id, filter } => {
                self.connect_base_pending_log_stream(id, filter).await
            }
            SubscriberStreamSource::BaseFlashblocks => self.connect_base_flashblock_stream().await,
            SubscriberStreamSource::OpPendingFlashblocks => {
                self.connect_op_flashblock_tick_stream()
            }
            SubscriberStreamSource::PubSubPendingHashes => {
                self.connect_pubsub_pending_hash_stream().await
            }
            SubscriberStreamSource::PubSubBlockHeaders => {
                self.connect_pubsub_block_header_stream().await
            }
            SubscriberStreamSource::PollingLog { filter } => {
                self.connect_polling_log_stream(filter).await
            }
            SubscriberStreamSource::PollingPendingHashes => {
                self.connect_polling_pending_hash_stream().await
            }
        }
    }

    async fn connect_pubsub_log_stream(
        &mut self,
        id: usize,
        filter: Filter,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-ws")]
        {
            let source = SubscriberStreamSource::PubSubLog {
                id,
                filter: filter.clone(),
            };
            let stream = self
                .provider
                .subscribe_logs(&filter)
                .channel_size(self.config.max_batch_size.max(1))
                .await
                .map_err(provider_error)?
                .into_stream()
                .map(move |log| SubscriberEvent::Log { source_id: id, log });
            Ok(stream_with_termination(stream, source))
        }

        #[cfg(not(feature = "reactive-ws"))]
        {
            let _ = (id, filter);
            Err(SubscriberError::Unsupported(
                "AlloySubscriber pubsub mode requires the reactive-ws feature",
            ))
        }
    }

    async fn connect_base_pending_log_stream(
        &mut self,
        id: usize,
        filter: Filter,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-ws")]
        {
            let source = SubscriberStreamSource::BasePendingLog {
                id,
                filter: filter.clone(),
            };
            let params = base_pending_log_filter(&filter)?;
            let stream = self
                .provider
                .subscribe::<_, Log>(("pendingLogs", params))
                .channel_size(self.config.max_batch_size.max(1))
                .await
                .map_err(provider_error)?
                .into_stream()
                .map(move |log| SubscriberEvent::BasePendingLog { source_id: id, log });
            Ok(stream_with_termination(stream, source))
        }

        #[cfg(not(feature = "reactive-ws"))]
        {
            let _ = (id, filter);
            Err(SubscriberError::Unsupported(
                "Base Flashblocks require the reactive-ws feature",
            ))
        }
    }

    async fn connect_base_flashblock_stream(
        &mut self,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-ws")]
        {
            let stream = self
                .provider
                .subscribe::<_, BaseFlashblockWirePayload>(("newFlashblocks",))
                .channel_size(self.config.max_batch_size.max(1))
                .await
                .map_err(provider_error)?
                .into_stream()
                .map(SubscriberEvent::BaseFlashblock);
            Ok(stream_with_termination(
                stream,
                SubscriberStreamSource::BaseFlashblocks,
            ))
        }

        #[cfg(not(feature = "reactive-ws"))]
        {
            Err(SubscriberError::Unsupported(
                "Base Flashblocks require the reactive-ws feature",
            ))
        }
    }

    fn connect_op_flashblock_tick_stream(
        &self,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        let interval = tokio::time::interval(self.config.flashblock_poll_interval);
        let stream = stream::unfold(interval, |mut interval| async move {
            interval.tick().await;
            Some((SubscriberEvent::OpFlashblockTick, interval))
        });
        Ok(stream_with_termination(
            stream,
            SubscriberStreamSource::OpPendingFlashblocks,
        ))
    }

    async fn connect_pubsub_pending_hash_stream(
        &mut self,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-ws")]
        {
            let stream = self
                .provider
                .subscribe_pending_transactions()
                .channel_size(self.config.max_batch_size.max(1))
                .await
                .map_err(provider_error)?
                .into_stream()
                .map(SubscriberEvent::PendingHash);
            Ok(stream_with_termination(
                stream,
                SubscriberStreamSource::PubSubPendingHashes,
            ))
        }

        #[cfg(not(feature = "reactive-ws"))]
        {
            Err(SubscriberError::Unsupported(
                "AlloySubscriber pubsub mode requires the reactive-ws feature",
            ))
        }
    }

    async fn connect_pubsub_block_header_stream(
        &mut self,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-ws")]
        {
            let stream = self
                .provider
                .subscribe_blocks()
                .channel_size(self.config.max_batch_size.max(1))
                .await
                .map_err(provider_error)?
                .into_stream()
                .map(SubscriberEvent::BlockHeader);
            Ok(stream_with_termination(
                stream,
                SubscriberStreamSource::PubSubBlockHeaders,
            ))
        }

        #[cfg(not(feature = "reactive-ws"))]
        {
            Err(SubscriberError::Unsupported(
                "AlloySubscriber pubsub mode requires the reactive-ws feature",
            ))
        }
    }

    async fn connect_polling_log_stream(
        &mut self,
        filter: Filter,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-polling")]
        {
            let source = SubscriberStreamSource::PollingLog {
                filter: filter.clone(),
            };
            let stream = self
                .provider
                .watch_logs(&filter)
                .await
                .map_err(provider_error)?
                .with_channel_size(self.config.max_batch_size.max(1))
                .into_stream()
                .map(SubscriberEvent::Logs);
            Ok(stream_with_termination(stream, source))
        }

        #[cfg(not(feature = "reactive-polling"))]
        {
            let _ = filter;
            Err(SubscriberError::Unsupported(
                "AlloySubscriber polling mode requires the reactive-polling feature",
            ))
        }
    }

    async fn connect_polling_pending_hash_stream(
        &mut self,
    ) -> Result<BoxStream<'static, SubscriberEvent<N>>, SubscriberError> {
        #[cfg(feature = "reactive-polling")]
        {
            let stream = self
                .provider
                .watch_pending_transactions()
                .await
                .map_err(provider_error)?
                .with_channel_size(self.config.max_batch_size.max(1))
                .into_stream()
                .map(SubscriberEvent::PendingHashes);
            Ok(stream_with_termination(
                stream,
                SubscriberStreamSource::PollingPendingHashes,
            ))
        }

        #[cfg(not(feature = "reactive-polling"))]
        {
            Err(SubscriberError::Unsupported(
                "AlloySubscriber polling mode requires the reactive-polling feature",
            ))
        }
    }

    async fn next_event(&mut self) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        loop {
            let event = match &mut self.state {
                AlloySubscriberState::Active(streams) => streams.next().await,
                AlloySubscriberState::Uninitialized | AlloySubscriberState::Empty => {
                    return Ok(None);
                }
            };

            let Some(event) = event else {
                return Err(SubscriberError::Provider(
                    "Alloy subscriber streams terminated before the subscriber was stopped"
                        .to_owned(),
                ));
            };

            match event {
                SubscriberEvent::StreamTerminated(source) => {
                    // Persist the missing-source intent before the first await.
                    // If a control command cancels this poll during reconnect,
                    // the next poll will reconcile the desired/live diff.
                    self.sources_dirty = true;
                    self.bump_stream_revision();
                    if source.is_flashblocks() {
                        self.reset_flashblock_tracking();
                    }
                    if let Some(backfill_event) = self.reconnect_source_stream(source).await? {
                        self.sources_dirty = false;
                        if let Some(backfill_event) =
                            self.normalize_flashblock_event(backfill_event).await?
                        {
                            self.verify_event_log_blocks(&backfill_event).await?;
                            return Ok(Some(backfill_event));
                        }
                    }
                    self.sources_dirty = false;
                }
                event => {
                    let Some(event) = self.normalize_flashblock_event(event).await? else {
                        continue;
                    };
                    self.verify_event_log_blocks(&event).await?;
                    return Ok(Some(event));
                }
            }
        }
    }

    async fn normalize_flashblock_event(
        &mut self,
        event: SubscriberEvent<N>,
    ) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        match event {
            SubscriberEvent::BasePendingLog { source_id, log } => {
                let hash = log.block_hash.ok_or_else(|| {
                    SubscriberError::Provider(
                        "Base pendingLogs item is missing its partial block hash".into(),
                    )
                })?;
                let Some(flashblock) = self.flashblocks_by_hash.get(&hash).cloned() else {
                    if self.unmatched_pending_logs.len() >= self.config.max_pending_records {
                        return Err(SubscriberError::ResourceExhausted(
                            "unmatched Base pendingLogs exceeded max_pending_records".into(),
                        ));
                    }
                    self.unmatched_pending_logs.push_back((source_id, log));
                    return Ok(None);
                };
                let logs = self.filter_preconfirmed_logs(&flashblock, vec![log])?;
                Ok(Some(if logs.is_empty() {
                    SubscriberEvent::FlashblockObserved
                } else {
                    SubscriberEvent::PreconfirmedLogs { flashblock, logs }
                }))
            }
            SubscriberEvent::BaseFlashblock(payload) => {
                let (flashblock, recover_pending_snapshot) =
                    self.accept_base_flashblock(payload)?;
                let mut logs = Vec::new();
                let mut retained = VecDeque::new();
                while let Some((source_id, log)) = self.unmatched_pending_logs.pop_front() {
                    if log.block_hash == Some(flashblock.block_hash) {
                        let _ = source_id;
                        logs.push(log);
                    } else {
                        retained.push_back((source_id, log));
                    }
                }
                self.unmatched_pending_logs = retained;

                if recover_pending_snapshot
                    && let Some(event) = self.fetch_pending_flashblock().await?
                {
                    return Ok(Some(event));
                }
                let logs = self.filter_preconfirmed_logs(&flashblock, logs)?;
                Ok(Some(if logs.is_empty() {
                    SubscriberEvent::FlashblockObserved
                } else {
                    SubscriberEvent::PreconfirmedLogs { flashblock, logs }
                }))
            }
            SubscriberEvent::OpFlashblockTick => self.fetch_pending_flashblock().await,
            SubscriberEvent::PreconfirmedLogs { flashblock, logs } => {
                let logs = self.filter_preconfirmed_logs(&flashblock, logs)?;
                Ok(Some(if logs.is_empty() {
                    SubscriberEvent::FlashblockObserved
                } else {
                    SubscriberEvent::PreconfirmedLogs { flashblock, logs }
                }))
            }
            SubscriberEvent::FlashblockObserved => Ok(None),
            event => Ok(Some(event)),
        }
    }

    fn accept_base_flashblock(
        &mut self,
        payload: BaseFlashblockWirePayload,
    ) -> Result<(FlashblockRef, bool), SubscriberError> {
        let provider = self.provider_ref.clone().ok_or({
            SubscriberError::InvalidConfig(
                "Flashblocks require a stable provider ref from a pinned provider lease",
            )
        })?;

        let (flashblock, recover_pending_snapshot) = match payload {
            BaseFlashblockWirePayload::Indexed(payload) => {
                if payload.index == 0 {
                    let base = payload.base.clone().ok_or_else(|| {
                        SubscriberError::Provider(
                            "Base newFlashblocks index zero omitted its base header".into(),
                        )
                    })?;
                    self.base_flashblock_header = Some((payload.payload_id, base));
                }

                let base = self
                    .base_flashblock_header
                    .as_ref()
                    .filter(|(payload_id, _)| *payload_id == payload.payload_id)
                    .map(|(_, base)| base);
                let block_number = base.map(|base| base.block_number).or_else(|| {
                    payload
                        .metadata
                        .as_ref()
                        .map(|metadata| metadata.block_number)
                });
                let block_number = block_number.ok_or_else(|| {
                    SubscriberError::Provider(
                        "Base newFlashblocks payload omitted both base and metadata block number"
                            .into(),
                    )
                })?;
                let flashblock = FlashblockRef {
                    provider,
                    payload_id: Some(payload.payload_id),
                    index: Some(payload.index),
                    block_number,
                    block_hash: payload.diff.block_hash,
                    parent_hash: base.map(|base| base.parent_hash),
                    state_root: Some(payload.diff.state_root),
                    timestamp: base.map(|base| base.timestamp),
                };
                let recover = match self.latest_preconfirmation.as_ref() {
                    Some(previous) if previous.same_payload(&flashblock) => {
                        if let (Some(previous), Some(current)) = (previous.index, flashblock.index)
                        {
                            if current < previous {
                                return Ok((flashblock, false));
                            }
                            current > previous.saturating_add(1)
                        } else {
                            false
                        }
                    }
                    Some(_) => payload.index != 0,
                    None => payload.index != 0,
                };
                (flashblock, recover)
            }
            BaseFlashblockWirePayload::Block(payload) => {
                let index = self
                    .latest_preconfirmation
                    .as_ref()
                    .filter(|previous| {
                        previous.block_number == payload.number
                            && previous.parent_hash == Some(payload.parent_hash)
                    })
                    .and_then(|previous| previous.index)
                    .map_or(0, |index| index.saturating_add(1));
                (
                    FlashblockRef {
                        provider,
                        payload_id: None,
                        index: Some(index),
                        block_number: payload.number,
                        block_hash: payload.hash,
                        parent_hash: Some(payload.parent_hash),
                        state_root: Some(payload.state_root),
                        timestamp: Some(payload.timestamp),
                    },
                    false,
                )
            }
        };

        self.flashblocks_by_hash
            .insert(flashblock.block_hash, flashblock.clone());
        self.flashblock_hash_order.push_back(flashblock.block_hash);
        while self.flashblock_hash_order.len() > 64 {
            if let Some(hash) = self.flashblock_hash_order.pop_front() {
                self.flashblocks_by_hash.remove(&hash);
            }
        }
        Ok((flashblock, recover_pending_snapshot))
    }

    async fn fetch_pending_flashblock(
        &mut self,
    ) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        let latest = self
            .provider
            .get_block_number()
            .await
            .map_err(provider_error)?;
        let Some(block) = self
            .provider
            .get_block_by_number(BlockNumberOrTag::Pending)
            .await
            .map_err(provider_error)?
        else {
            if self.config.preconfirmations == PreconfirmationMode::Required {
                return Err(SubscriberError::Provider(
                    "Flashblocks provider returned no pending block".into(),
                ));
            }
            return Ok(None);
        };
        let header = block.header();
        if header.number() <= latest {
            if self.config.preconfirmations == PreconfirmationMode::Required {
                return Err(SubscriberError::Provider(
                    "Flashblocks provider pending state did not advance beyond the canonical head"
                        .into(),
                ));
            }
            return Ok(None);
        }

        let provider = self.provider_ref.clone().ok_or({
            SubscriberError::InvalidConfig(
                "Flashblocks require a stable provider ref from a pinned provider lease",
            )
        })?;
        let parent_hash = Some(header.parent_hash());
        let index = self.latest_preconfirmation.as_ref().and_then(|previous| {
            (previous.block_number == header.number() && previous.parent_hash == parent_hash)
                .then(|| previous.index.unwrap_or(0).saturating_add(1))
        });
        let flashblock = FlashblockRef {
            provider,
            payload_id: None,
            index: Some(index.unwrap_or(0)),
            block_number: header.number(),
            block_hash: header.hash(),
            parent_hash,
            state_root: Some(header.state_root()),
            timestamp: Some(header.timestamp()),
        };
        if self
            .latest_preconfirmation
            .as_ref()
            .is_some_and(|previous| {
                previous.block_hash == flashblock.block_hash
                    && previous.block_number == flashblock.block_number
            })
        {
            return Ok(None);
        }

        let logs = self.fetch_pending_logs().await?;
        let logs = self.filter_preconfirmed_logs(&flashblock, logs)?;
        Ok(Some(if logs.is_empty() {
            SubscriberEvent::FlashblockObserved
        } else {
            SubscriberEvent::PreconfirmedLogs { flashblock, logs }
        }))
    }

    async fn fetch_pending_logs(&mut self) -> Result<Vec<Log>, SubscriberError> {
        let mut logs = Vec::new();
        for filter in self.log_stream_filters() {
            let filter = filter
                .from_block(BlockNumberOrTag::Pending)
                .to_block(BlockNumberOrTag::Pending);
            logs.extend(
                self.provider
                    .get_logs(&filter)
                    .await
                    .map_err(provider_error)?,
            );
        }
        Ok(logs)
    }

    fn filter_preconfirmed_logs(
        &mut self,
        flashblock: &FlashblockRef,
        mut logs: Vec<Log>,
    ) -> Result<Vec<Log>, SubscriberError> {
        if self
            .latest_preconfirmation
            .as_ref()
            .is_none_or(|previous| !previous.same_payload(flashblock))
        {
            self.preconfirmed_seen_logs.clear();
        }
        if let Some(previous) = self.latest_preconfirmation.as_ref()
            && previous.same_payload(flashblock)
            && let (Some(previous_index), Some(current_index)) = (previous.index, flashblock.index)
            && current_index < previous_index
        {
            return Ok(Vec::new());
        }
        self.latest_preconfirmation = Some(flashblock.clone());

        logs.sort_by_key(|log| (log.transaction_index.unwrap_or(u64::MAX), log.log_index));
        let mut filtered = Vec::new();
        for log in logs {
            if log.removed
                || log.block_number != Some(flashblock.block_number)
                || log.block_hash != Some(flashblock.block_hash)
            {
                return Err(SubscriberError::Provider(
                    "pre-confirmed log disagrees with its Flashblock snapshot".into(),
                ));
            }
            let transaction_hash = log.transaction_hash.ok_or_else(|| {
                SubscriberError::Provider(
                    "pre-confirmed log is missing its transaction hash".into(),
                )
            })?;
            let log_index = log.log_index.ok_or_else(|| {
                SubscriberError::Provider("pre-confirmed log is missing its log index".into())
            })?;
            if self
                .preconfirmed_seen_logs
                .insert((transaction_hash, log_index))
                && log_matches_any_interest(&log, &self.interests)
            {
                filtered.push(log);
            }
        }
        Ok(filtered)
    }

    async fn verify_event_log_blocks(
        &mut self,
        event: &SubscriberEvent<N>,
    ) -> Result<(), SubscriberError> {
        if !self.config.verify_log_block_context {
            return Ok(());
        }
        match event {
            SubscriberEvent::Log { log, .. } => self.verify_log_block_context(log).await,
            SubscriberEvent::BackfilledLogs { logs, .. } | SubscriberEvent::Logs(logs) => {
                for log in logs {
                    self.verify_log_block_context(log).await?;
                }
                Ok(())
            }
            SubscriberEvent::BlockHeader(_)
            | SubscriberEvent::PendingHash(_)
            | SubscriberEvent::PendingHashes(_)
            | SubscriberEvent::BasePendingLog { .. }
            | SubscriberEvent::BaseFlashblock(_)
            | SubscriberEvent::OpFlashblockTick
            | SubscriberEvent::PreconfirmedLogs { .. }
            | SubscriberEvent::FlashblockObserved
            | SubscriberEvent::StreamTerminated(_) => Ok(()),
        }
    }

    async fn verify_log_block_context(&mut self, log: &Log) -> Result<(), SubscriberError> {
        if log.removed {
            return Ok(());
        }
        let number = log.block_number.ok_or_else(|| {
            SubscriberError::Provider(
                "canonical log is missing its block number during context verification".into(),
            )
        })?;
        let hash = log.block_hash.ok_or_else(|| {
            SubscriberError::Provider(
                "canonical log is missing its block hash during context verification".into(),
            )
        })?;
        let key = (number, hash);
        if self.verified_log_blocks.contains_key(&key) {
            return Ok(());
        }
        let provider = self
            .log_verification_provider
            .as_ref()
            .unwrap_or(&self.provider);
        let block = provider
            .get_block_by_number(BlockNumberOrTag::Number(number))
            .await
            .map_err(provider_error)?
            .ok_or_else(|| {
                SubscriberError::Provider(format!(
                    "canonical log block {number} is unavailable during context verification"
                ))
            })?;
        let header = block.header();
        let verified = BlockRef {
            number: header.number(),
            hash: header.hash(),
            parent_hash: Some(header.parent_hash()),
            timestamp: Some(header.timestamp()),
        };
        if verified.number != number
            || verified.hash != hash
            || log
                .block_timestamp
                .is_some_and(|timestamp| verified.timestamp != Some(timestamp))
        {
            return Err(SubscriberError::Provider(format!(
                "canonical log block {number}:{hash:?} disagrees with the provider's current canonical identity"
            )));
        }
        self.verified_log_blocks.insert(key, verified);
        self.verified_log_block_order.push_back(key);
        let capacity = self.config.reconnect.dedupe_window.max(1);
        while self.verified_log_block_order.len() > capacity {
            if let Some(evicted) = self.verified_log_block_order.pop_front() {
                self.verified_log_blocks.remove(&evicted);
            }
        }
        Ok(())
    }

    fn enqueue_event(&mut self, event: SubscriberEvent<N>) {
        self.enqueue_event_with_excluded_owners(event, None);
    }

    fn buffer_reconcile_event_for_owners(
        &mut self,
        event: &SubscriberEvent<N>,
        target_epochs: &HashSet<SubscriberOwnerEpoch>,
    ) {
        match event {
            SubscriberEvent::Log { log, .. } => {
                self.buffer_reconcile_log_for_owners(log, InputSource::Subscription, target_epochs)
            }
            SubscriberEvent::BackfilledLogs { logs, .. } => {
                for log in logs {
                    self.buffer_reconcile_log_for_owners(log, InputSource::Backfill, target_epochs);
                }
            }
            SubscriberEvent::Logs(logs) => {
                for log in logs {
                    self.buffer_reconcile_log_for_owners(log, InputSource::Poll, target_epochs);
                }
            }
            SubscriberEvent::BlockHeader(_)
            | SubscriberEvent::PendingHash(_)
            | SubscriberEvent::PendingHashes(_)
            | SubscriberEvent::BasePendingLog { .. }
            | SubscriberEvent::BaseFlashblock(_)
            | SubscriberEvent::OpFlashblockTick
            | SubscriberEvent::PreconfirmedLogs { .. }
            | SubscriberEvent::FlashblockObserved
            | SubscriberEvent::StreamTerminated(_) => {}
        }
    }

    fn buffer_reconcile_log_for_owners(
        &mut self,
        log: &Log,
        source: InputSource,
        target_epochs: &HashSet<SubscriberOwnerEpoch>,
    ) {
        let record = self.with_chain_id(log_input_record(log.clone(), source));
        let owners = self
            .staged_owners_for_record(&record)
            .into_iter()
            .filter(|owner| target_epochs.contains(owner))
            .collect::<Vec<_>>();
        if !owners.is_empty() {
            self.push_pending_reconcile_record(BufferedSubscriberOwnerRecord { record, owners });
        }
    }

    fn promote_reconcile_owner_records(&mut self, target_epochs: &HashSet<SubscriberOwnerEpoch>) {
        let mut retained = VecDeque::new();
        while let Some(mut buffered) = self.pending_reconcile_owner_records.pop_front() {
            let mut promoted = Vec::new();
            buffered.owners.retain(|owner| {
                if target_epochs.contains(owner) {
                    promoted.push(owner.clone());
                    false
                } else {
                    true
                }
            });
            if promoted.is_empty() {
                retained.push_back(buffered);
                continue;
            }
            let promoted_record = if buffered.owners.is_empty() {
                buffered.record
            } else {
                let record = buffered.record.clone();
                retained.push_back(buffered);
                record
            };
            self.enqueue_owner_record_for_owners_unmerged(promoted_record, promoted);
        }
        self.pending_reconcile_owner_records = retained;
    }

    fn seed_reconciled_filter_anchors(
        &mut self,
        plans: &[SubscriberOwnerReconcilePlan<N>],
        through: u64,
    ) {
        for filter in plans.iter().flat_map(|plan| log_filters(&plan.interests)) {
            let Some(source_id) = self.log_source_ids.get(&filter).copied() else {
                continue;
            };
            let anchor = self
                .last_seen_log_blocks
                .entry(source_id)
                .or_insert(through);
            *anchor = (*anchor).max(through);
        }
    }

    fn enqueue_event_excluding_owners(
        &mut self,
        event: SubscriberEvent<N>,
        excluded: &HashSet<SubscriberOwnerEpoch>,
    ) {
        self.enqueue_event_with_excluded_owners(event, Some(excluded));
    }

    fn enqueue_event_with_excluded_owners(
        &mut self,
        event: SubscriberEvent<N>,
        excluded: Option<&HashSet<SubscriberOwnerEpoch>>,
    ) {
        match event {
            SubscriberEvent::Log { source_id, log } => {
                if log_matches_any_interest(&log, &self.interests) {
                    let record = log_input_record(log, InputSource::Subscription);
                    self.note_log_block(source_id, &record);
                    self.enqueue_record_with_excluded_owners(record, excluded);
                }
            }
            SubscriberEvent::BackfilledLogs { source_id, logs } => {
                self.enqueue_backfilled_logs_with_excluded_owners(
                    logs,
                    Some(source_id),
                    None,
                    None,
                    excluded,
                );
            }
            SubscriberEvent::Logs(logs) => {
                for log in logs {
                    if log_matches_any_interest(&log, &self.interests) {
                        self.enqueue_record_with_excluded_owners(
                            log_input_record(log, InputSource::Poll),
                            excluded,
                        );
                    }
                }
            }
            SubscriberEvent::BlockHeader(header) => {
                if needs_header_block_stream(&self.interests) {
                    let record = block_header_input_record::<N>(header);
                    self.enqueue_record_with_excluded_owners(record, excluded);
                }
            }
            SubscriberEvent::PendingHash(hash) => {
                let record = pending_hash_input_record::<N>(hash, InputSource::Subscription);
                self.enqueue_record_with_excluded_owners(record, excluded);
            }
            SubscriberEvent::PendingHashes(hashes) => {
                for hash in hashes {
                    self.enqueue_record_with_excluded_owners(
                        pending_hash_input_record::<N>(hash, InputSource::Poll),
                        excluded,
                    );
                }
            }
            SubscriberEvent::PreconfirmedLogs { flashblock, logs } => {
                for log in logs {
                    let record = self
                        .with_chain_id(preconfirmed_log_input_record::<N>(log, flashblock.clone()));
                    self.push_pending_record(SubscriberInputRecord {
                        record,
                        scope: SubscriberInputScope::Preconfirmed,
                    });
                }
            }
            SubscriberEvent::BasePendingLog { .. }
            | SubscriberEvent::BaseFlashblock(_)
            | SubscriberEvent::OpFlashblockTick
            | SubscriberEvent::FlashblockObserved => {}
            SubscriberEvent::StreamTerminated(_) => {}
        }
    }

    fn enqueue_backfilled_logs(
        &mut self,
        logs: Vec<Log>,
        source_id: Option<usize>,
        owner: Option<&SubscriberOwnerEpoch>,
        range: Option<SubscriberBackfill>,
    ) {
        self.enqueue_backfilled_logs_with_excluded_owners(logs, source_id, owner, range, None);
    }

    fn enqueue_backfilled_logs_with_excluded_owners(
        &mut self,
        logs: Vec<Log>,
        source_id: Option<usize>,
        owner: Option<&SubscriberOwnerEpoch>,
        range: Option<SubscriberBackfill>,
        excluded: Option<&HashSet<SubscriberOwnerEpoch>>,
    ) {
        for log in logs {
            if range.as_ref().is_some_and(|range| {
                log.block_number.is_some_and(|block| {
                    block < range.start_block() || range.end_block().is_some_and(|end| block > end)
                })
            }) {
                continue;
            }
            let matches = match owner {
                Some(epoch) => self
                    .owned_interests
                    .iter()
                    .find(|entry| entry.epoch.as_ref() == Some(epoch))
                    .is_some_and(|entry| log_matches_any_interest(&log, &entry.interests)),
                None => log_matches_any_interest(&log, &self.interests),
            };
            if matches {
                let record = log_input_record(log, InputSource::Backfill);
                if let Some(epoch) = owner {
                    self.enqueue_owner_record(record, epoch.clone());
                } else {
                    if let Some(source_id) = source_id {
                        self.note_log_block(source_id, &record);
                    }
                    self.enqueue_record_with_excluded_owners(record, excluded);
                }
            }
        }
    }

    fn enqueue_compat_owner_backfilled_logs(
        &mut self,
        logs: Vec<Log>,
        owner: &HandlerId,
        range: SubscriberBackfill,
    ) {
        let interests = self
            .owned_interests
            .iter()
            .find(|entry| {
                &entry.owner == owner
                    && entry.epoch.is_none()
                    && entry.state == SubscriberOwnerState::Active
            })
            .map(|entry| entry.interests.clone());
        let Some(interests) = interests else {
            return;
        };
        for log in logs {
            if log.block_number.is_some_and(|block| {
                block < range.start_block() || range.end_block().is_some_and(|end| block > end)
            }) || !log_matches_any_interest(&log, &interests)
            {
                continue;
            }
            let record = log_input_record(log, InputSource::Backfill);
            self.enqueue_compat_owner_record(record, owner.clone());
        }
    }

    async fn reconnect_source_stream(
        &mut self,
        source: SubscriberStreamSource,
    ) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        if !source.is_pubsub() {
            return Err(stream_terminated_error(&source));
        }

        if !self.config.reconnect.enabled {
            return Err(SubscriberError::Provider(format!(
                "Alloy subscriber {} stream terminated and reconnect is disabled",
                source.label()
            )));
        }

        let mut attempts = 0usize;
        let mut delay = self.config.reconnect.initial_delay;
        let mut retry_delay = self.config.reconnect.retry_delay;

        loop {
            attempts = attempts.saturating_add(1);
            if !delay.is_zero() {
                tokio::time::sleep(delay).await;
            }

            match self.reconnect_source_once(source.clone()).await {
                Ok(backfill_event) => return Ok(backfill_event),
                Err(error) if reconnect_attempts_exhausted(attempts, &self.config.reconnect) => {
                    return Err(SubscriberError::Provider(format!(
                        "Alloy subscriber {} stream terminated and reconnect failed after {attempts} attempt(s): {error}",
                        source.label()
                    )));
                }
                Err(error) => {
                    tracing::warn!(
                        stream = source.label(),
                        attempts,
                        error = %error,
                        "Alloy subscriber reconnect attempt failed"
                    );
                    delay = retry_delay;
                    retry_delay =
                        next_reconnect_delay(retry_delay, self.config.reconnect.max_delay);
                }
            }
        }
    }

    async fn reconnect_source_once(
        &mut self,
        source: SubscriberStreamSource,
    ) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        if matches!(
            &self.state,
            AlloySubscriberState::Active(streams) if streams.contains_source(&source)
        ) {
            // A prior attempt installed the stream before its catch-up await
            // failed or was cancelled. Retry only the unfinished historical
            // window; reconnecting again would create a duplicate live source.
            let backfill_event = self.backfill_reconnected_source(&source).await?;
            self.pending_source_backfills
                .retain(|pending| !pending.same_key(&source));
            return Ok(backfill_event);
        }
        let stream = self.connect_source_stream(source.clone()).await?;
        if !matches!(self.state, AlloySubscriberState::Active(_)) {
            return Err(SubscriberError::Provider(
                "Alloy subscriber state changed before reconnect completed".to_owned(),
            ));
        }
        self.install_source_stream(source.clone(), stream);
        if self.source_requires_backfill(&source) {
            self.queue_source_backfill(source.clone());
        }
        let backfill_event = self.backfill_reconnected_source(&source).await?;
        self.pending_source_backfills
            .retain(|pending| !pending.same_key(&source));

        Ok(backfill_event)
    }

    async fn backfill_reconnected_source(
        &mut self,
        source: &SubscriberStreamSource,
    ) -> Result<Option<SubscriberEvent<N>>, SubscriberError> {
        if source.is_flashblocks() {
            return self.fetch_pending_flashblock().await;
        }
        let SubscriberStreamSource::PubSubLog { id, filter } = source else {
            return Ok(None);
        };
        let Some(from_block) = self.last_seen_log_blocks.get(id).copied() else {
            return Ok(None);
        };

        let latest = self
            .provider
            .get_block_number()
            .await
            .map_err(provider_error)?;
        if latest < from_block {
            return Ok(None);
        }

        let logs = self
            .provider
            .get_logs(&filter.clone().from_block(from_block).to_block(latest))
            .await
            .map_err(provider_error)?;
        Ok(Some(SubscriberEvent::BackfilledLogs {
            source_id: *id,
            logs,
        }))
    }

    fn note_log_block(&mut self, source_id: usize, record: &ReactiveInputRecord<N>) {
        if let Some(block) = record.context.block.as_ref() {
            self.last_seen_log_blocks.insert(source_id, block.number);
        }
    }

    fn enqueue_record_with_excluded_owners(
        &mut self,
        record: ReactiveInputRecord<N>,
        excluded: Option<&HashSet<SubscriberOwnerEpoch>>,
    ) {
        let record = self.with_chain_id(record);
        let mut owners = self.staged_owners_for_record(&record);
        if let Some(excluded) = excluded {
            owners.retain(|owner| !excluded.contains(owner));
        }
        let canonical_duplicate = self.should_skip_recent_duplicate(&record);
        let owners = self.filter_recent_owner_duplicates(&record, owners);
        let compatibility_owners = self.compatibility_owners_for_record(&record);
        let (already_served, newly_served): (Vec<_>, Vec<_>) = compatibility_owners
            .into_iter()
            .partition(|owner| self.compatibility_owner_has_seen(&record, owner));
        if canonical_duplicate {
            if !owners.is_empty() {
                self.push_pending_record(SubscriberInputRecord {
                    record: record.clone(),
                    scope: SubscriberInputScope::OwnerOnly { owners },
                });
            }
            if !newly_served.is_empty() {
                for owner in &newly_served {
                    self.remember_compatibility_owner_record(&record, owner);
                }
                self.push_pending_record(SubscriberInputRecord {
                    record,
                    scope: SubscriberInputScope::OwnerOnlyHandlers {
                        owners: newly_served,
                    },
                });
            }
            return;
        }
        self.remember_record(&record);
        for owner in already_served.iter().chain(&newly_served) {
            self.remember_compatibility_owner_record(&record, owner);
        }
        self.push_pending_record(SubscriberInputRecord {
            record,
            scope: if already_served.is_empty() {
                SubscriberInputScope::Canonical { owners }
            } else {
                SubscriberInputScope::CanonicalResidual {
                    owners,
                    excluded: already_served,
                }
            },
        });
    }

    fn enqueue_compat_owner_record(&mut self, record: ReactiveInputRecord<N>, owner: HandlerId) {
        let record = self.with_chain_id(record);
        if self.compatibility_owner_has_seen(&record, &owner) {
            return;
        }
        self.remember_compatibility_owner_record(&record, &owner);
        self.push_pending_record(SubscriberInputRecord {
            record,
            scope: SubscriberInputScope::OwnerOnlyHandlers {
                owners: vec![owner],
            },
        });
    }

    fn compatibility_owners_for_record(&self, record: &ReactiveInputRecord<N>) -> Vec<HandlerId> {
        self.owned_interests
            .iter()
            .filter(|entry| entry.epoch.is_none() && entry.state == SubscriberOwnerState::Active)
            .filter(|entry| {
                entry
                    .interests
                    .iter()
                    .any(|interest| interest_matches(interest, &record.input))
            })
            .map(|entry| entry.owner.clone())
            .collect()
    }

    fn compatibility_owner_has_seen(
        &self,
        record: &ReactiveInputRecord<N>,
        owner: &HandlerId,
    ) -> bool {
        should_dedupe_record(record)
            && self
                .recent_compat_owner_input_ref_sets
                .get(owner)
                .is_some_and(|seen| seen.contains(&record.input_ref()))
    }

    fn remember_compatibility_owner_record(
        &mut self,
        record: &ReactiveInputRecord<N>,
        owner: &HandlerId,
    ) {
        if !should_dedupe_record(record) || self.config.reconnect.dedupe_window == 0 {
            return;
        }
        let input_ref = record.input_ref();
        let seen = self
            .recent_compat_owner_input_ref_sets
            .entry(owner.clone())
            .or_default();
        if !seen.insert(input_ref) {
            return;
        }
        let recent = self
            .recent_compat_owner_input_refs
            .entry(owner.clone())
            .or_default();
        recent.push_back(input_ref);
        while recent.len() > self.config.reconnect.dedupe_window {
            if let Some(evicted) = recent.pop_front() {
                seen.remove(&evicted);
            }
        }
    }

    fn enqueue_owner_record(
        &mut self,
        record: ReactiveInputRecord<N>,
        owner: SubscriberOwnerEpoch,
    ) {
        self.enqueue_owner_record_for_owners(record, vec![owner]);
    }

    fn enqueue_owner_record_for_owners(
        &mut self,
        record: ReactiveInputRecord<N>,
        owners: Vec<SubscriberOwnerEpoch>,
    ) {
        self.enqueue_owner_record_for_owners_inner(record, owners, true);
    }

    fn enqueue_owner_record_for_owners_unmerged(
        &mut self,
        record: ReactiveInputRecord<N>,
        owners: Vec<SubscriberOwnerEpoch>,
    ) {
        self.enqueue_owner_record_for_owners_inner(record, owners, false);
    }

    fn enqueue_owner_record_for_owners_inner(
        &mut self,
        record: ReactiveInputRecord<N>,
        owners: Vec<SubscriberOwnerEpoch>,
        merge_pending: bool,
    ) {
        let record = self.with_chain_id(record);
        let owners = self.filter_recent_owner_duplicates(&record, owners);
        if owners.is_empty() {
            return;
        }
        if merge_pending
            && should_dedupe_record(&record)
            && self.config.reconnect.dedupe_window != 0
        {
            let input_ref = record.input_ref();
            if let Some(pending) = self
                .pending_records
                .iter_mut()
                .rev()
                .find(|pending| pending.record.input_ref() == input_ref)
            {
                let pending_owners = match &mut pending.scope {
                    SubscriberInputScope::Canonical { owners }
                    | SubscriberInputScope::CanonicalResidual { owners, .. }
                    | SubscriberInputScope::OwnerOnly { owners } => Some(owners),
                    SubscriberInputScope::OwnerOnlyHandlers { .. }
                    | SubscriberInputScope::Preconfirmed => None,
                };
                if let Some(pending_owners) = pending_owners {
                    for owner in owners {
                        if !pending_owners.contains(&owner) {
                            pending_owners.push(owner);
                        }
                    }
                    return;
                }
            }
        }
        self.push_pending_record(SubscriberInputRecord {
            record,
            scope: SubscriberInputScope::OwnerOnly { owners },
        });
    }

    fn push_pending_record(&mut self, record: SubscriberInputRecord<N>) {
        if self.pending_record_count() >= self.config.max_pending_records {
            self.note_resource_error(format!(
                "pending record queues reached the configured limit of {}",
                self.config.max_pending_records
            ));
            return;
        }
        self.pending_records.push_back(record);
    }

    fn ensure_pending_record_capacity(
        &mut self,
        additional: usize,
        operation: &str,
    ) -> Result<(), SubscriberError> {
        let required = self.pending_record_count().saturating_add(additional);
        if required > self.config.max_pending_records {
            self.note_resource_error(format!(
                "{operation} require {required} pending records, above the configured limit of {}",
                self.config.max_pending_records
            ));
            return self.check_resource_error();
        }
        Ok(())
    }

    fn push_pending_reconcile_record(&mut self, record: BufferedSubscriberOwnerRecord<N>) {
        if self.pending_record_count() >= self.config.max_pending_records {
            self.note_resource_error(format!(
                "pending record queues reached the configured limit of {}",
                self.config.max_pending_records
            ));
            return;
        }
        self.pending_reconcile_owner_records.push_back(record);
    }

    fn pending_record_count(&self) -> usize {
        self.pending_records
            .len()
            .saturating_add(self.pending_reconcile_owner_records.len())
    }

    fn note_resource_error(&mut self, message: String) {
        if self.resource_error.is_none() {
            self.resource_error = Some(message);
        }
    }

    fn check_resource_error(&self) -> Result<(), SubscriberError> {
        match &self.resource_error {
            Some(message) => Err(SubscriberError::ResourceExhausted(message.clone())),
            None => Ok(()),
        }
    }

    fn with_chain_id(&self, mut record: ReactiveInputRecord<N>) -> ReactiveInputRecord<N> {
        record.context.chain_id = self.chain_id;
        if self.config.verify_log_block_context
            && let ReactiveInput::Log(log) = &record.input
            && !log.removed
            && let (Some(number), Some(hash)) = (log.block_number, log.block_hash)
            && let Some(verified) = self.verified_log_blocks.get(&(number, hash)).copied()
        {
            record.context.block = Some(verified);
            record.context.chain_status = ChainStatus::Included {
                block: verified,
                confirmations: 0,
            };
        }
        record
    }

    fn staged_owners_for_record(
        &self,
        record: &ReactiveInputRecord<N>,
    ) -> Vec<SubscriberOwnerEpoch> {
        self.owned_interests
            .iter()
            .filter(|entry| entry.state == SubscriberOwnerState::Staged)
            .filter(|entry| {
                entry
                    .interests
                    .iter()
                    .any(|interest| interest_matches(interest, &record.input))
            })
            .filter_map(|entry| entry.epoch.clone())
            .collect()
    }

    fn filter_recent_owner_duplicates(
        &mut self,
        record: &ReactiveInputRecord<N>,
        owners: Vec<SubscriberOwnerEpoch>,
    ) -> Vec<SubscriberOwnerEpoch> {
        if !should_dedupe_record(record) || self.config.reconnect.dedupe_window == 0 {
            return owners;
        }
        let input_ref = record.input_ref();
        let window = self.config.reconnect.dedupe_window;
        owners
            .into_iter()
            .filter(|owner| {
                let seen = self
                    .recent_owner_input_ref_sets
                    .entry(owner.clone())
                    .or_default();
                if !seen.insert(input_ref) {
                    return false;
                }
                let recent = self
                    .recent_owner_input_refs
                    .entry(owner.clone())
                    .or_default();
                recent.push_back(input_ref);
                while recent.len() > window {
                    if let Some(evicted) = recent.pop_front() {
                        seen.remove(&evicted);
                    }
                }
                true
            })
            .collect()
    }

    fn should_skip_recent_duplicate(&self, record: &ReactiveInputRecord<N>) -> bool {
        if !should_dedupe_record(record) {
            return false;
        }
        self.recent_input_ref_set.contains(&record.input_ref())
    }

    fn remember_record(&mut self, record: &ReactiveInputRecord<N>) {
        if !should_dedupe_record(record) || self.config.reconnect.dedupe_window == 0 {
            return;
        }

        let input_ref = record.input_ref();
        if !self.recent_input_ref_set.insert(input_ref) {
            return;
        }
        self.recent_input_refs.push_back(input_ref);

        while self.recent_input_refs.len() > self.config.reconnect.dedupe_window {
            if let Some(evicted) = self.recent_input_refs.pop_front() {
                self.recent_input_ref_set.remove(&evicted);
            }
        }
    }
}

fn stream_with_termination<N, S>(
    stream: S,
    source: SubscriberStreamSource,
) -> BoxStream<'static, SubscriberEvent<N>>
where
    N: Network + 'static,
    S: futures::Stream<Item = SubscriberEvent<N>> + Send + 'static,
{
    stream
        .chain(stream::once(async move {
            SubscriberEvent::StreamTerminated(source)
        }))
        .boxed()
}

fn aggregate_interests<N: Network>(
    base: &[ReactiveInterest<N>],
    owned: &[OwnedSubscriberInterests<N>],
) -> Vec<ReactiveInterest<N>> {
    base.iter()
        .cloned()
        .chain(
            owned
                .iter()
                .flat_map(|entry| entry.interests.iter().cloned()),
        )
        .collect()
}

fn stream_terminated_error(source: &SubscriberStreamSource) -> SubscriberError {
    SubscriberError::Provider(format!(
        "Alloy subscriber {} stream terminated before the subscriber was stopped",
        source.label()
    ))
}

fn reconnect_attempts_exhausted(attempts: usize, config: &SubscriberReconnectConfig) -> bool {
    config
        .max_attempts
        .is_some_and(|max_attempts| attempts >= max_attempts)
}

fn next_reconnect_delay(current: Duration, max: Duration) -> Duration {
    if current.is_zero() {
        return current;
    }
    current.checked_mul(2).unwrap_or(max).min(max)
}

fn should_dedupe_record<N: Network>(record: &ReactiveInputRecord<N>) -> bool {
    match &record.input {
        ReactiveInput::Log(log) => {
            is_canonical_status(&record.context.chain_status) && !log.removed
        }
        ReactiveInput::BlockHeader(_) | ReactiveInput::PendingTxHash(_) => true,
        ReactiveInput::FullBlock(_) | ReactiveInput::PendingTx(_) => false,
    }
}

#[cfg(test)]
mod subscriber_helper_tests {
    use super::*;
    use alloy_provider::ProviderBuilder;
    use alloy_transport::mock::Asserter;

    #[test]
    fn base_flashblock_wire_decodes_cumulative_block_shape() {
        let payload: BaseFlashblockWirePayload = serde_json::from_str(
            r#"{
                "hash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "number":"0x2ef403b",
                "parentHash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                "stateRoot":"0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
                "timestamp":"0x6a68dd59",
                "transactions":[]
            }"#,
        )
        .expect("decode current Base newFlashblocks shape");
        let BaseFlashblockWirePayload::Block(payload) = payload else {
            panic!("expected cumulative block-shaped payload")
        };
        assert_eq!(payload.number, 49_233_979);
        assert_eq!(payload.timestamp, 1_785_257_305);
        assert_eq!(payload.hash, B256::repeat_byte(0xaa));
        assert_eq!(payload.parent_hash, B256::repeat_byte(0xbb));
        assert_eq!(payload.state_root, B256::repeat_byte(0xcc));
    }

    #[test]
    fn unproven_parent_replacement_rewind_discards_every_unauthenticated_identity() {
        let parent = BlockRef {
            number: 79,
            hash: B256::repeat_byte(0x79),
            parent_hash: Some(B256::repeat_byte(0x78)),
            timestamp: Some(1_700_000_079),
        };
        let old_tip = BlockRef {
            number: 80,
            hash: B256::repeat_byte(0x80),
            parent_hash: Some(parent.hash),
            timestamp: Some(1_700_000_080),
        };
        let replacement = BlockRef {
            hash: B256::repeat_byte(0xe0),
            parent_hash: Some(B256::repeat_byte(0xdf)),
            ..old_tip
        };
        let mut state =
            CanonicalSequenceState::new(vec![parent, old_tip], Some(old_tip), Some(parent), None);

        let rewind = apply_sequence_canonical_block(&mut state, &replacement, false)
            .expect("replacement metadata is structurally valid")
            .expect("unknown parent is an observable rewind");

        assert_eq!(rewind.common_ancestor, None);
        assert_eq!(rewind.dropped, vec![parent, old_tip]);
        assert_eq!(state.retained_canonical_history(), &[replacement]);
        assert_eq!(state.coverage_head(), Some(&replacement));
        assert_eq!(state.safe_head(), None);
        assert_eq!(state.finalized_head(), None);
    }

    #[test]
    fn handler_ids_are_non_empty_across_construction_and_deserialization() {
        assert_eq!(HandlerId::try_new("").unwrap_err(), HandlerIdError);
        let valid = HandlerId::try_new("owner-1").expect("non-empty id");
        let encoded = serde_json::to_string(&valid).expect("serialize id");
        assert_eq!(
            serde_json::from_str::<HandlerId>(&encoded).expect("deserialize valid id"),
            valid
        );
        assert!(serde_json::from_str::<HandlerId>(r#"""#).is_err());
    }

    fn rpc_log(removed: bool) -> Log {
        Log {
            inner: alloy_primitives::Log::new_unchecked(
                Address::repeat_byte(0x42),
                vec![B256::repeat_byte(0x01)],
                Bytes::new(),
            ),
            block_hash: Some(B256::repeat_byte(0x02)),
            block_number: Some(7),
            block_timestamp: Some(1_700_000_000),
            transaction_hash: Some(B256::repeat_byte(0x03)),
            transaction_index: Some(4),
            log_index: Some(5),
            removed,
        }
    }

    fn rpc_transaction(chain_id: Option<u64>) -> alloy_rpc_types_eth::Transaction {
        use alloy_consensus::SignableTransaction as _;

        let envelope: alloy_consensus::TxEnvelope = alloy_consensus::TxLegacy {
            chain_id,
            ..Default::default()
        }
        .into_signed(alloy_primitives::Signature::test_signature())
        .into();
        alloy_rpc_types_eth::Transaction {
            inner: alloy_consensus::transaction::Recovered::new_unchecked(envelope, Address::ZERO),
            block_hash: None,
            block_number: None,
            transaction_index: None,
            effective_gas_price: None,
        }
    }

    #[cfg(feature = "reactive-ws")]
    fn rpc_log_at(block_number: u64, transaction_index: u64, log_index: u64) -> Log {
        Log {
            inner: alloy_primitives::Log::new_unchecked(
                Address::repeat_byte(0x42),
                vec![B256::repeat_byte(0x01)],
                Bytes::new(),
            ),
            block_hash: Some(B256::repeat_byte(block_number as u8)),
            block_number: Some(block_number),
            block_timestamp: Some(1_700_000_000 + block_number),
            transaction_hash: Some(B256::repeat_byte(0x20 + transaction_index as u8)),
            transaction_index: Some(transaction_index),
            log_index: Some(log_index),
            removed: false,
        }
    }

    #[cfg(any(feature = "reactive-polling", feature = "reactive-ws"))]
    fn rpc_block(number: u64, hash: B256) -> alloy_rpc_types_eth::Block {
        alloy_rpc_types_eth::Block::empty(alloy_rpc_types_eth::Header {
            hash,
            inner: alloy_consensus::Header {
                number,
                parent_hash: B256::repeat_byte(number.saturating_sub(1) as u8),
                timestamp: 1_700_000_000 + number,
                ..Default::default()
            },
            total_difficulty: None,
            size: None,
        })
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn verified_log_context_fetches_and_caches_exact_parent_identity() {
        let stream_asserter = Asserter::new();
        let provider = ProviderBuilder::new().connect_mocked_client(stream_asserter.clone());
        let verification_asserter = Asserter::new();
        verification_asserter.push_success(&Some(rpc_block(7, B256::repeat_byte(7))));
        let verification_provider =
            ProviderBuilder::new().connect_mocked_client(verification_asserter.clone());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig {
                verify_log_block_context: true,
                ..SubscriberConfig::default()
            },
        )
        .with_log_verification_provider(verification_provider);
        let log = rpc_log_at(7, 0, 0);

        subscriber
            .verify_log_block_context(&log)
            .await
            .expect("verify live log block");
        subscriber
            .verify_log_block_context(&log)
            .await
            .expect("reuse verified block cache");
        let record = subscriber.with_chain_id(log_input_record(log, InputSource::Subscription));

        assert_eq!(
            record.context.block.expect("verified block").parent_hash,
            Some(B256::repeat_byte(6))
        );
        assert!(
            verification_asserter.read_q().is_empty(),
            "one provider lookup should verify every log in the same block"
        );
        assert!(
            stream_asserter.read_q().is_empty(),
            "verification must not use the high-volume stream provider"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn stream_with_termination_yields_terminal_source_marker() {
        let mut stream = stream_with_termination::<Ethereum, _>(
            stream::iter([SubscriberEvent::<Ethereum>::PendingHash(B256::repeat_byte(
                0xaa,
            ))]),
            SubscriberStreamSource::PubSubPendingHashes,
        );

        assert!(matches!(
            stream.next().await,
            Some(SubscriberEvent::PendingHash(hash)) if hash == B256::repeat_byte(0xaa)
        ));
        assert!(matches!(
            stream.next().await,
            Some(SubscriberEvent::StreamTerminated(source)) if source.is_pubsub()
        ));
        assert!(stream.next().await.is_none());
    }

    #[test]
    fn reconnect_delay_doubles_until_capped() {
        assert_eq!(
            next_reconnect_delay(Duration::from_millis(250), Duration::from_secs(1)),
            Duration::from_millis(500)
        );
        assert_eq!(
            next_reconnect_delay(Duration::from_millis(750), Duration::from_secs(1)),
            Duration::from_secs(1)
        );
        assert_eq!(
            next_reconnect_delay(Duration::ZERO, Duration::from_secs(1)),
            Duration::ZERO
        );
    }

    #[test]
    fn canonical_logs_are_deduped_but_removed_logs_are_not() {
        let included = log_input_record::<Ethereum>(rpc_log(false), InputSource::Subscription);
        let removed = log_input_record::<Ethereum>(rpc_log(true), InputSource::Subscription);

        assert!(should_dedupe_record(&included));
        assert!(!should_dedupe_record(&removed));
    }

    #[test]
    fn owner_reconcile_dedupe_rejects_conflicts_and_preserves_compatible_enrichment() {
        let set_context_timestamp = |record: &mut ReactiveInputRecord<Ethereum>,
                                     timestamp: Option<u64>| {
            record.context.block.as_mut().expect("block").timestamp = timestamp;
            match &mut record.context.chain_status {
                ChainStatus::Included { block, .. }
                | ChainStatus::Safe { block }
                | ChainStatus::Finalized { block }
                | ChainStatus::Reorged {
                    dropped_from: block,
                } => block.timestamp = timestamp,
                ChainStatus::Pending | ChainStatus::Preconfirmed { .. } => {
                    panic!("log record is canonical")
                }
            }
        };

        let mut payload_only = log_input_record::<Ethereum>(rpc_log(false), InputSource::Backfill);
        let payload_timestamp = match &payload_only.input {
            ReactiveInput::Log(log) => log.block_timestamp.expect("timestamp"),
            _ => unreachable!(),
        };
        set_context_timestamp(&mut payload_only, None);
        let mut context_only = payload_only.clone();
        if let ReactiveInput::Log(log) = &mut context_only.input {
            log.block_timestamp = None;
        }
        set_context_timestamp(&mut context_only, Some(payload_timestamp + 1));
        assert!(matches!(
            dedupe_records(vec![payload_only, context_only]),
            Err(ReactiveError::InvalidInputRecord { .. })
        ));

        let mut partial = log_input_record::<Ethereum>(rpc_log(false), InputSource::Backfill);
        if let ReactiveInput::Log(log) = &mut partial.input {
            log.block_timestamp = None;
        }
        set_context_timestamp(&mut partial, None);
        let complete = log_input_record::<Ethereum>(rpc_log(false), InputSource::Subscription);
        let deduped =
            dedupe_records(vec![partial, complete]).expect("compatible metadata enriches");
        assert_eq!(deduped.len(), 1);
        deduped[0]
            .validated_identity()
            .expect("merged record remains coherent");
        let resolved = resolve_record_block_payload_metadata(
            &deduped[0],
            *canonical_record_block(&deduped[0]).expect("canonical"),
        )
        .expect("effective block");
        assert_eq!(resolved.timestamp, Some(payload_timestamp));
    }

    #[test]
    fn full_block_bodies_are_never_suppressed_from_header_hash_alone() {
        use alloy_rpc_types_eth::{Block, Header};

        let block_ref = BlockRef {
            number: 7,
            hash: B256::repeat_byte(0x77),
            parent_hash: Some(B256::repeat_byte(0x66)),
            timestamp: Some(1_700_000_007),
        };
        let block = Block::empty(Header {
            hash: block_ref.hash,
            inner: alloy_consensus::Header {
                number: block_ref.number,
                parent_hash: block_ref.parent_hash.expect("parent"),
                timestamp: block_ref.timestamp.expect("timestamp"),
                ..Default::default()
            },
            total_difficulty: None,
            size: None,
        });
        let record = ReactiveInputRecord::<Ethereum>::new(
            ReactiveInput::FullBlock(block),
            ReactiveContext {
                chain_id: Some(1),
                source: InputSource::Subscription,
                chain_status: ChainStatus::Included {
                    block: block_ref,
                    confirmations: 0,
                },
                block: Some(block_ref),
                transaction_index: None,
                log_index: None,
            },
        );

        assert!(!record.is_payload_deduplicable());
        assert!(!record.same_deduplicable_payload(&record));
        let retained = dedupe_scoped_records(vec![
            (
                record.clone(),
                DeliveryAudience::All,
                DeliveryScope::Canonical,
            ),
            (record, DeliveryAudience::All, DeliveryScope::Canonical),
        ])
        .expect("non-deduplicable bodies are preserved, not treated as conflicts");
        assert_eq!(retained.len(), 2);
    }

    #[test]
    fn hydrated_transaction_wrappers_reject_inclusion_and_chain_identity_conflicts() {
        let pending_context = ReactiveContext {
            chain_id: Some(1),
            source: InputSource::Batch,
            chain_status: ChainStatus::Pending,
            block: None,
            transaction_index: None,
            log_index: None,
        };
        let mut included_pending = rpc_transaction(Some(1));
        included_pending.block_hash = Some(B256::repeat_byte(0xaa));
        assert!(matches!(
            ReactiveInputRecord::<Ethereum>::new(
                ReactiveInput::PendingTx(included_pending),
                pending_context.clone(),
            )
            .validated_identity(),
            Err(ReactiveError::InvalidInputRecord { .. })
        ));
        assert!(matches!(
            ReactiveInputRecord::<Ethereum>::new(
                ReactiveInput::PendingTx(rpc_transaction(Some(2))),
                pending_context,
            )
            .validated_identity(),
            Err(ReactiveError::InvalidInputRecord { .. })
        ));

        let block_ref = BlockRef {
            number: 8,
            hash: B256::repeat_byte(0x88),
            parent_hash: Some(B256::repeat_byte(0x77)),
            timestamp: Some(1_700_000_008),
        };
        let header = alloy_rpc_types_eth::Header {
            hash: block_ref.hash,
            inner: alloy_consensus::Header {
                number: block_ref.number,
                parent_hash: block_ref.parent_hash.expect("parent"),
                timestamp: block_ref.timestamp.expect("timestamp"),
                ..Default::default()
            },
            total_difficulty: None,
            size: None,
        };
        let context = ReactiveContext {
            chain_id: Some(1),
            source: InputSource::Batch,
            chain_status: ChainStatus::Included {
                block: block_ref,
                confirmations: 0,
            },
            block: Some(block_ref),
            transaction_index: None,
            log_index: None,
        };
        for transaction in [
            alloy_rpc_types_eth::Transaction {
                block_hash: Some(B256::repeat_byte(0xff)),
                ..rpc_transaction(Some(1))
            },
            alloy_rpc_types_eth::Transaction {
                block_hash: Some(block_ref.hash),
                block_number: Some(block_ref.number),
                transaction_index: Some(1),
                ..rpc_transaction(Some(1))
            },
            rpc_transaction(Some(2)),
        ] {
            let block = alloy_rpc_types_eth::Block::new(
                header.clone(),
                alloy_network::primitives::BlockTransactions::Full(vec![transaction]),
            );
            assert!(matches!(
                ReactiveInputRecord::<Ethereum>::new(
                    ReactiveInput::FullBlock(block),
                    context.clone(),
                )
                .validated_identity(),
                Err(ReactiveError::InvalidInputRecord { .. })
            ));
        }
    }

    #[test]
    fn compatibility_owner_backfill_and_live_overlap_split_exact_audiences() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig::default(),
        );
        let owner = HandlerId::new("compat-owner");
        subscriber
            .add_interest_owner(
                owner.clone(),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
                    local_matcher: None,
                    route_key: None,
                })],
            )
            .unwrap();
        let log = rpc_log(false);

        subscriber.enqueue_compat_owner_record(
            log_input_record(log.clone(), InputSource::Backfill),
            owner.clone(),
        );
        subscriber.enqueue_event(SubscriberEvent::Log { source_id: 0, log });

        let batch = subscriber
            .drain_next_scoped_batch()
            .expect("owner catch-up and residual live copies");
        assert_eq!(batch.records.len(), 2);
        assert_eq!(
            batch.records[0].scope,
            SubscriberInputScope::OwnerOnlyHandlers {
                owners: vec![owner.clone()]
            }
        );
        assert_eq!(
            batch.records[1].scope,
            SubscriberInputScope::CanonicalResidual {
                owners: Vec::new(),
                excluded: vec![owner.clone()]
            }
        );

        let reactive = batch.into_reactive_batch();
        assert_eq!(
            reactive.record_audience(0),
            Some(&DeliveryAudience::Owners(vec![owner.clone()]))
        );
        assert_eq!(
            reactive.record_delivery_scope(0),
            Some(DeliveryScope::OwnerCatchup)
        );
        assert_eq!(
            reactive.record_audience(1),
            Some(&DeliveryAudience::AllExcept(vec![owner]))
        );
        assert_eq!(
            reactive.record_delivery_scope(1),
            Some(DeliveryScope::Canonical)
        );
    }

    #[test]
    fn active_owner_replacement_commits_atomically_to_one_new_epoch() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig::default(),
        );
        let owner = HandlerId::new("replace-owner");
        let original = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x41)),
            local_matcher: None,
            route_key: None,
        });
        let replacement_interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let active = subscriber
            .stage_interest_owner(owner.clone(), &[original], SubscriberOwnerStart::Live)
            .unwrap();
        assert!(subscriber.activate_interest_owner(&active));
        let replacement = subscriber
            .stage_interest_owner_replacement(
                owner,
                &[replacement_interest],
                SubscriberOwnerStart::Live,
            )
            .unwrap();

        assert!(subscriber.commit_interest_owner_replacement(&active, &replacement));
        assert_eq!(subscriber.interest_owner_state(&active), None);
        assert_eq!(
            subscriber.interest_owner_state(&replacement),
            Some(SubscriberOwnerState::Active)
        );
        assert_eq!(subscriber.registered_interests().len(), 1);
    }

    #[test]
    fn compatibility_and_epoch_owner_lifecycles_cannot_mix() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig::default(),
        );
        let owner = HandlerId::new("one-lifecycle");
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                owner.clone(),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::Live,
            )
            .expect("stage epoch owner");

        assert!(matches!(
            subscriber.add_interest_owner(owner.clone(), std::slice::from_ref(&interest)),
            Err(SubscriberError::InvalidConfig(_))
        ));
        assert_eq!(
            subscriber.interest_owner_state(&epoch),
            Some(SubscriberOwnerState::Staged)
        );
        assert!(subscriber.abort_interest_owner(&epoch));
        subscriber
            .add_interest_owner(owner.clone(), std::slice::from_ref(&interest))
            .expect("compatibility owner after epoch abort");
        assert!(matches!(
            subscriber.stage_interest_owner_replacement(
                owner,
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::Live,
            ),
            Err(SubscriberOwnerError::AlreadyRegistered(_))
        ));
    }

    #[test]
    fn pending_record_overflow_is_sticky_and_fail_closed() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig {
                max_pending_records: 1,
                ..SubscriberConfig::default()
            },
        );
        subscriber.interests = vec![ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        })];
        subscriber.enqueue_event(SubscriberEvent::Log {
            source_id: 0,
            log: rpc_log(false),
        });
        let mut second = rpc_log(false);
        second.log_index = Some(6);
        second.transaction_hash = Some(B256::repeat_byte(0x04));
        subscriber.enqueue_event(SubscriberEvent::Log {
            source_id: 0,
            log: second,
        });

        assert_eq!(subscriber.pending_records.len(), 1);
        assert!(matches!(
            subscriber.check_resource_error(),
            Err(SubscriberError::ResourceExhausted(_))
        ));
        subscriber.reset_delivery_state();
        assert!(subscriber.check_resource_error().is_ok());
    }

    #[test]
    fn historical_log_payload_bytes_are_bounded_independently_of_log_count() {
        let baseline = rpc_log(false);
        let fixed_bytes =
            validate_backfill_resource_limits(std::slice::from_ref(&baseline), 1, usize::MAX)
                .expect("measure fixed log accounting");
        let mut large = baseline;
        large.inner = alloy_primitives::Log::new_unchecked(
            Address::repeat_byte(0x42),
            vec![B256::repeat_byte(0x01)],
            Bytes::from(vec![0u8; 256]),
        );

        assert!(matches!(
            validate_backfill_resource_limits(&[large], 1, fixed_bytes + 255),
            Err(SubscriberError::ResourceExhausted(_))
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-polling")]
    async fn reconcile_capacity_failure_does_not_publish_progress_or_partial_history() {
        use alloy_rpc_types_eth::{Block, Header};

        let asserter = Asserter::new();
        let baseline = BlockRef {
            number: 6,
            hash: B256::repeat_byte(6),
            parent_hash: Some(B256::repeat_byte(5)),
            timestamp: Some(1_700_000_006),
        };
        let through = BlockRef {
            number: 7,
            hash: B256::repeat_byte(7),
            parent_hash: Some(baseline.hash),
            timestamp: Some(1_700_000_007),
        };
        let rpc_block = || -> Block {
            Block::empty(Header {
                hash: through.hash,
                inner: alloy_consensus::Header {
                    number: through.number,
                    parent_hash: through.parent_hash.expect("parent"),
                    timestamp: through.timestamp.expect("timestamp"),
                    ..Default::default()
                },
                total_difficulty: None,
                size: None,
            })
        };
        let mut historical = rpc_log(false);
        historical.block_hash = Some(through.hash);
        historical.block_timestamp = through.timestamp;
        asserter.push_success(&Some(rpc_block()));
        asserter.push_success(&vec![historical]);
        asserter.push_success(&Some(rpc_block()));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig {
                max_pending_records: 1,
                ..SubscriberConfig::default()
            },
        );
        subscriber.chain_id = Some(1);
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("capacity-owner"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::PostBlock(baseline),
            )
            .expect("stage owner");
        // Isolate the commit-side capacity edge: the live queue acquired one
        // canonical record while the historical request was in flight.
        subscriber.sources_dirty = false;
        subscriber.state = AlloySubscriberState::Empty;
        subscriber.push_pending_record(SubscriberInputRecord {
            record: log_input_record(rpc_log(false), InputSource::Poll),
            scope: SubscriberInputScope::Canonical { owners: Vec::new() },
        });

        let error = subscriber
            .reconcile_interest_owner(&epoch, through)
            .await
            .expect_err("historical delivery cannot displace the queued live record");
        assert!(matches!(
            error,
            SubscriberOwnerError::Subscriber(SubscriberError::ResourceExhausted(_))
        ));
        assert!(subscriber.interest_owner_progress(&epoch).is_none());
        assert_eq!(subscriber.pending_records.len(), 1);
        assert!(matches!(
            subscriber.pending_records[0].scope,
            SubscriberInputScope::Canonical { .. }
        ));
    }

    #[test]
    fn lazy_backfill_queue_capacity_failure_is_atomic() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig {
                max_pending_backfills: 1,
                ..SubscriberConfig::default()
            },
        );
        let interest = |address| {
            ReactiveInterest::Logs(LogInterest {
                provider_filter: Filter::new().address(address),
                local_matcher: None,
                route_key: None,
            })
        };
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("owner-a"),
                &[interest(Address::repeat_byte(0x41))],
                SubscriberBackfill::from_block(10),
            )
            .expect("first queued backfill");

        let error = subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("owner-b"),
                &[interest(Address::repeat_byte(0x42))],
                SubscriberBackfill::from_block(10),
            )
            .expect_err("second backfill must exceed capacity");

        assert!(matches!(error, SubscriberError::ResourceExhausted(_)));
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("owner-b"))
                .is_none()
        );
        assert_eq!(subscriber.pending_backfills.len(), 1);
    }

    #[test]
    fn exact_owner_replacement_is_atomic_and_removes_crash_stale_owners() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig {
                max_pending_backfills: 1,
                ..SubscriberConfig::default()
            },
        );
        let interest = |address| {
            ReactiveInterest::Logs(LogInterest {
                provider_filter: Filter::new().address(address),
                local_matcher: None,
                route_key: None,
            })
        };
        subscriber
            .add_interest_owner(
                HandlerId::new("crash-stale"),
                &[interest(Address::repeat_byte(0xee))],
            )
            .expect("seed stale owner");
        subscriber.base_interests = vec![interest(Address::repeat_byte(0xdd))];
        subscriber.rebuild_registered_interests();
        subscriber.push_pending_record(SubscriberInputRecord {
            record: log_input_record(rpc_log(false), InputSource::Poll),
            scope: SubscriberInputScope::Canonical { owners: Vec::new() },
        });
        let baseline = BlockRef {
            number: 100,
            hash: B256::repeat_byte(100),
            parent_hash: Some(B256::repeat_byte(99)),
            timestamp: Some(1_700_000_100),
        };
        let backfill = SubscriberBackfill::after_canonical_block(baseline).expect("C + 1");

        let error = subscriber
            .replace_interest_owners_with_global_backfill(
                vec![
                    (
                        HandlerId::new("pool-a"),
                        vec![interest(Address::repeat_byte(0xa1))],
                    ),
                    (
                        HandlerId::new("pool-b"),
                        vec![ReactiveInterest::Logs(LogInterest {
                            // A distinct block option prevents provider-filter
                            // fan-in, exercising the two-unit capacity edge.
                            provider_filter: Filter::new()
                                .address(Address::repeat_byte(0xb2))
                                .from_block(7),
                            local_matcher: None,
                            route_key: None,
                        })],
                    ),
                ],
                backfill,
            )
            .expect_err("two backfills exceed atomic capacity");
        assert!(matches!(error, SubscriberError::ResourceExhausted(_)));
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("crash-stale"))
                .is_some(),
            "failed replacement must preserve the prior topology"
        );
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("pool-a"))
                .is_none()
        );
        assert_eq!(subscriber.base_interests.len(), 1);
        assert_eq!(subscriber.pending_records.len(), 1);

        subscriber
            .replace_interest_owners_with_global_backfill(
                vec![(
                    HandlerId::new("pool-a"),
                    vec![interest(Address::repeat_byte(0xa1))],
                )],
                backfill,
            )
            .expect("replacement within capacity");
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("crash-stale"))
                .is_none(),
            "successful exact replacement removes stale owners"
        );
        assert!(
            subscriber.base_interests.is_empty(),
            "successful exact replacement removes stale unowned interests"
        );
        assert!(
            subscriber.drain_next_scoped_batch().is_none(),
            "stale canonical delivery must not escape before C + 1 recovery"
        );
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("pool-a"))
                .is_some()
        );
        assert_eq!(subscriber.pending_backfills.len(), 1);
        assert_eq!(subscriber.pending_backfills[0].backfill, backfill);
        assert!(
            subscriber.pending_backfills[0].owner.is_none(),
            "startup history must be global canonical catch-up, not owner-only"
        );
    }

    #[test]
    fn exclusive_canonical_backfill_rejects_block_number_overflow() {
        let baseline = BlockRef {
            number: u64::MAX,
            hash: B256::repeat_byte(0xff),
            parent_hash: None,
            timestamp: None,
        };
        assert!(matches!(
            SubscriberBackfill::after_canonical_block(baseline),
            Err(SubscriberError::InvalidConfig(_))
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn exclusive_canonical_backfill_validates_the_retained_baseline_hash() {
        let asserter = Asserter::new();
        asserter.push_success(&101u64);
        asserter.push_success(&Some(rpc_block(101, B256::repeat_byte(101))));
        asserter.push_success(&Some(rpc_block(100, B256::repeat_byte(0xee))));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig::default(),
        );
        let baseline = BlockRef {
            number: 100,
            hash: B256::repeat_byte(0xaa),
            parent_hash: None,
            timestamp: None,
        };
        let backfill = SubscriberBackfill::after_canonical_block(baseline).expect("C + 1");
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("pool"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0xa1)),
                    local_matcher: None,
                    route_key: None,
                })],
                backfill,
            )
            .expect("queue post-baseline backfill");

        let error = subscriber
            .drain_pending_backfills()
            .await
            .expect_err("provider branch differs at retained baseline");
        assert!(matches!(error, SubscriberError::InvalidBackfill(_)));
        assert_eq!(subscriber.pending_backfills.len(), 1);
        assert_eq!(subscriber.pending_backfills[0].backfill.start_block(), 101);
        assert!(subscriber.pending_records.is_empty());
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn coordinated_multifilter_windows_are_globally_sorted_for_owner_and_canonical_delivery()
    {
        let asserter = Asserter::new();
        let retained = BlockRef {
            number: 10,
            hash: B256::repeat_byte(10),
            parent_hash: Some(B256::repeat_byte(9)),
            timestamp: Some(1_700_000_010),
        };
        let activation = BlockRef {
            number: 12,
            hash: B256::repeat_byte(12),
            parent_hash: Some(B256::repeat_byte(11)),
            timestamp: Some(1_700_000_012),
        };

        // 257 distinct logical block options cross the 256-filter request
        // chunk boundary. Each window therefore makes two concurrent log
        // requests whose responses deliberately arrive in reverse order.
        asserter.push_success(&Some(rpc_block(retained.number, retained.hash)));
        asserter.push_success(&vec![rpc_log_at(10, 2, 2)]);
        asserter.push_success(&vec![rpc_log_at(10, 1, 1)]);
        asserter.push_success(&Some(rpc_block(retained.number, retained.hash)));
        asserter.push_success(&activation.number);
        asserter.push_success(&Some(rpc_block(activation.number, activation.hash)));
        asserter.push_success(&Some(rpc_block(retained.number, retained.hash)));
        asserter.push_success(&vec![rpc_log_at(12, 2, 2)]);
        asserter.push_success(&vec![rpc_log_at(11, 1, 1)]);
        asserter.push_success(&Some(rpc_block(activation.number, activation.hash)));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Auto,
            SubscriberConfig::default(),
        );
        let interests = (0..257)
            .map(|start| {
                ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new()
                        .address(Address::repeat_byte(0x42))
                        .event_signature(B256::repeat_byte(0x01))
                        .from_block(start),
                    local_matcher: None,
                    route_key: None,
                })
            })
            .collect::<Vec<_>>();
        subscriber
            .add_interest_owner_with_canonical_catchup(
                HandlerId::new("many-filters"),
                &interests,
                retained,
            )
            .expect("queue coordinated windows");
        assert_eq!(subscriber.pending_backfills.len(), 2);
        assert_eq!(subscriber.pending_backfills[0].filters.len(), 257);
        assert_eq!(subscriber.pending_backfills[1].filters.len(), 257);

        subscriber
            .drain_pending_backfills()
            .await
            .expect("owner filter group");
        let owner = subscriber
            .drain_next_scoped_batch()
            .expect("owner ordered batch");
        assert_eq!(owner.records.len(), 2);
        assert_eq!(owner.records[0].record.context.transaction_index, Some(1));
        assert_eq!(owner.records[1].record.context.transaction_index, Some(2));
        assert!(
            owner.records.iter().all(|record| matches!(
                record.scope,
                SubscriberInputScope::OwnerOnlyHandlers { .. }
            ))
        );

        subscriber
            .drain_pending_backfills()
            .await
            .expect("global filter group");
        let global = subscriber
            .drain_next_scoped_batch()
            .expect("global ordered batch");
        assert_eq!(global.records.len(), 2);
        assert_eq!(
            global.records[0].record.context.block.map(|b| b.number),
            Some(11)
        );
        assert_eq!(
            global.records[1].record.context.block.map(|b| b.number),
            Some(12)
        );
        assert!(
            global
                .records
                .iter()
                .all(|record| record.scope.is_canonical())
        );
        assert!(matches!(
            global.chain_controls.as_slice(),
            [ChainControl::Barrier {
                block: Some(block),
                ..
            }] if block == &activation
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn aborting_staged_epoch_purges_only_its_buffered_delivery() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let owner_a = subscriber
            .stage_interest_owner(
                HandlerId::new("owner-a"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::Live,
            )
            .unwrap();
        let owner_b = subscriber
            .stage_interest_owner(
                HandlerId::new("owner-b"),
                &[interest],
                SubscriberOwnerStart::Live,
            )
            .unwrap();

        subscriber.enqueue_event(SubscriberEvent::Log {
            source_id: 0,
            log: rpc_log(false),
        });
        assert!(subscriber.abort_interest_owner(&owner_a));

        let batch = subscriber
            .next_scoped_batch()
            .await
            .unwrap()
            .expect("shared canonical delivery remains queued");
        assert_eq!(batch.records.len(), 1);
        assert_eq!(
            batch.records[0].scope,
            SubscriberInputScope::Canonical {
                owners: vec![owner_b]
            }
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn owner_backfill_dedupe_never_suppresses_canonical_delivery() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("owner"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
                    local_matcher: None,
                    route_key: None,
                })],
                SubscriberOwnerStart::Live,
            )
            .unwrap();
        let log = rpc_log(false);

        subscriber.enqueue_owner_record(
            log_input_record(log.clone(), InputSource::Backfill),
            epoch.clone(),
        );
        subscriber.enqueue_event(SubscriberEvent::Log { source_id: 0, log });

        let batch = subscriber
            .next_scoped_batch()
            .await
            .unwrap()
            .expect("owner backfill and canonical live delivery");
        assert_eq!(batch.records.len(), 2);
        assert_eq!(
            batch.records[0].scope,
            SubscriberInputScope::OwnerOnly {
                owners: vec![epoch]
            }
        );
        assert_eq!(
            batch.records[1].scope,
            SubscriberInputScope::Canonical { owners: Vec::new() },
            "owner replay dedupe must not suppress the global live record"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-polling")]
    async fn reconcile_fetch_drains_live_burst_beyond_output_batch_capacity() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig {
                max_batch_size: 2,
                ..SubscriberConfig::default()
            },
        );
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("owner"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::Live,
            )
            .unwrap();
        subscriber.sources_dirty = false;

        let mut duplicate = rpc_log(false);
        duplicate.transaction_hash = Some(B256::repeat_byte(1));
        duplicate.log_index = Some(0);
        let events = (0u8..10).map(|index| {
            let mut log = rpc_log(false);
            log.transaction_hash = Some(B256::repeat_byte(index.saturating_add(1)));
            log.log_index = Some(index as u64);
            SubscriberEvent::Log { source_id: 0, log }
        });
        let filter = log_filters(std::slice::from_ref(&interest)).pop().unwrap();
        let mut streams = SubscriberStreams::new();
        streams.push(
            SubscriberStreamSource::PollingLog { filter },
            stream::iter(events).boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);

        let mut polls = 0usize;
        let fetched_duplicate = duplicate.clone();
        let fetch = poll_fn(move |cx| {
            polls += 1;
            if polls > 10 {
                std::task::Poll::Ready(Ok::<_, SubscriberOwnerError>(fetched_duplicate.clone()))
            } else {
                cx.waker().wake_by_ref();
                std::task::Poll::Pending
            }
        });
        let target_epochs = HashSet::from([epoch.clone()]);
        let fetched_duplicate = subscriber
            .drive_reconcile_fetch(fetch, &target_epochs)
            .await
            .unwrap();
        subscriber.enqueue_owner_record_for_owners_unmerged(
            log_input_record(fetched_duplicate, InputSource::Backfill),
            vec![epoch.clone()],
        );
        subscriber.promote_reconcile_owner_records(&target_epochs);

        assert_eq!(subscriber.pending_records.len(), 20);
        assert!(subscriber.pending_records.iter().take(10).all(|record| {
            record.scope == SubscriberInputScope::Canonical { owners: Vec::new() }
        }));
        assert!(subscriber.pending_records.iter().skip(10).all(|record| {
            record.scope
                == SubscriberInputScope::OwnerOnly {
                    owners: vec![epoch.clone()],
                }
        }));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-polling")]
    async fn reconcile_fetch_waits_for_provider_when_live_topology_is_empty() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        subscriber.sources_dirty = false;
        let mut first_poll = true;
        let fetch = poll_fn(move |cx| {
            if first_poll {
                first_poll = false;
                cx.waker().wake_by_ref();
                std::task::Poll::Pending
            } else {
                std::task::Poll::Ready(Ok::<_, SubscriberOwnerError>("certified"))
            }
        });

        let result = subscriber
            .drive_reconcile_fetch(fetch, &HashSet::new())
            .await
            .expect("an empty live topology must not be mistaken for termination");
        assert_eq!(result, "certified");
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(all(feature = "reactive-polling", feature = "reactive-ws"))]
    async fn successful_owner_reconcile_seeds_its_live_filter_reconnect_anchor() {
        use alloy_rpc_types_eth::{Block, Header};

        let asserter = Asserter::new();
        let baseline = BlockRef {
            number: 100,
            hash: B256::repeat_byte(0x64),
            parent_hash: Some(B256::repeat_byte(0x63)),
            timestamp: Some(1_700_000_100),
        };
        let through = BlockRef {
            number: 101,
            hash: B256::repeat_byte(0x65),
            parent_hash: Some(baseline.hash),
            timestamp: Some(1_700_000_101),
        };
        let rpc_block = || -> Block {
            Block::empty(Header {
                hash: through.hash,
                inner: alloy_consensus::Header {
                    number: through.number,
                    parent_hash: through.parent_hash.unwrap(),
                    timestamp: through.timestamp.unwrap(),
                    ..Default::default()
                },
                total_difficulty: None,
                size: None,
            })
        };
        asserter.push_success(&Some(rpc_block()));
        asserter.push_success(&Vec::<Log>::new());
        asserter.push_success(&Some(rpc_block()));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter.clone());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0xac)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("reconnect-anchor"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::PostBlock(baseline),
            )
            .unwrap();
        let filter = log_filters(std::slice::from_ref(&interest)).pop().unwrap();
        let source = SubscriberStreamSource::PubSubLog {
            id: subscriber.log_source_id(&filter),
            filter: filter.clone(),
        };
        let mut streams = SubscriberStreams::new();
        streams.push(source, stream::pending().boxed());
        subscriber.state = AlloySubscriberState::Active(streams);
        subscriber.sources_dirty = false;

        subscriber
            .reconcile_interest_owner(&epoch, through)
            .await
            .unwrap();
        assert_eq!(subscriber.log_anchor(&filter), Some(through.number));
        assert!(asserter.read_q().is_empty());
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-polling")]
    async fn cancelled_reconcile_retains_hidden_owner_live_delivery_for_retry() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig::default(),
        );
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("owner"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::PostBlock(BlockRef {
                    number: 100,
                    hash: B256::repeat_byte(0x64),
                    parent_hash: None,
                    timestamp: None,
                }),
            )
            .unwrap();
        subscriber.sources_dirty = false;

        let filter = log_filters(std::slice::from_ref(&interest)).pop().unwrap();
        let event = SubscriberEvent::Log {
            source_id: 0,
            log: rpc_log(false),
        };
        let mut streams = SubscriberStreams::new();
        streams.push(
            SubscriberStreamSource::PollingLog { filter },
            stream::once(async move { event })
                .chain(stream::pending())
                .boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);

        let targets = HashSet::from([epoch.clone()]);
        {
            let fetch = futures::future::pending::<Result<(), SubscriberOwnerError>>();
            let drive = subscriber.drive_reconcile_fetch(fetch, &targets);
            futures::pin_mut!(drive);
            poll_fn(|cx| {
                assert!(drive.as_mut().poll(cx).is_pending());
                std::task::Poll::Ready(())
            })
            .await;
        }

        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(
            subscriber.pending_records[0].scope,
            SubscriberInputScope::Canonical { owners: Vec::new() },
            "canonical delivery commits immediately at a cancellation-safe boundary"
        );
        assert_eq!(subscriber.pending_reconcile_owner_records.len(), 1);

        subscriber
            .drive_reconcile_fetch(futures::future::ready(Ok(())), &targets)
            .await
            .unwrap();
        subscriber.promote_reconcile_owner_records(&targets);
        assert!(subscriber.pending_reconcile_owner_records.is_empty());
        assert_eq!(subscriber.pending_records.len(), 2);
        assert_eq!(
            subscriber.pending_records[0].scope,
            SubscriberInputScope::Canonical { owners: Vec::new() },
            "canonical delivery remains target-excluded"
        );
        assert_eq!(
            subscriber.pending_records[1].scope,
            SubscriberInputScope::OwnerOnly {
                owners: vec![epoch]
            },
            "retry commit appends hidden owner delivery after historical catch-up"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn control_cancellation_preserves_terminated_source_reconcile_intent() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig {
                reconnect: SubscriberReconnectConfig {
                    initial_delay: Duration::from_secs(60),
                    ..SubscriberReconnectConfig::default()
                },
                ..SubscriberConfig::default()
            },
        );
        subscriber.chain_id = Some(1);
        let interest = ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(0x42)),
            local_matcher: None,
            route_key: None,
        });
        let epoch = subscriber
            .stage_interest_owner(
                HandlerId::new("owner"),
                std::slice::from_ref(&interest),
                SubscriberOwnerStart::PostBlock(BlockRef {
                    number: 7,
                    hash: B256::repeat_byte(0x07),
                    parent_hash: Some(B256::repeat_byte(0x06)),
                    timestamp: Some(1_700_000_007),
                }),
            )
            .unwrap();
        subscriber.sources_dirty = false;
        subscriber.stream_revision = 1;
        let entry = subscriber
            .owned_interests
            .iter_mut()
            .find(|entry| entry.epoch.as_ref() == Some(&epoch))
            .unwrap();
        entry.progress = Some(SubscriberOwnerProgress {
            owner: epoch.clone(),
            through: entry.baseline.unwrap(),
        });
        entry.progress_stream_revision = Some(1);

        let filter = log_filters(std::slice::from_ref(&interest)).pop().unwrap();
        let source = SubscriberStreamSource::PubSubLog {
            id: subscriber.log_source_id(&filter),
            filter,
        };
        let mut streams = SubscriberStreams::new();
        streams.push(
            source.clone(),
            stream::iter([SubscriberEvent::StreamTerminated(source)]).boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);
        let prior_revision = subscriber.stream_revision;

        let mut first_poll = true;
        let control = poll_fn(move |cx| {
            if first_poll {
                first_poll = false;
                cx.waker().wake_by_ref();
                std::task::Poll::Pending
            } else {
                std::task::Poll::Ready("stop")
            }
        });
        futures::pin_mut!(control);
        let outcome = subscriber
            .next_scoped_batch_or(control.as_mut())
            .await
            .unwrap();

        assert!(matches!(outcome, SubscriberDriverPoll::Control("stop")));
        assert!(subscriber.sources_dirty);
        assert!(subscriber.stream_revision > prior_revision);
        assert!(
            !subscriber.activate_interest_owner(&epoch),
            "progress certified against the terminated stream revision is stale"
        );
    }

    #[tokio::test]
    #[cfg(feature = "reactive-ws")]
    async fn pubsub_sources_assign_stable_log_ids_before_shared_streams() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        subscriber
            .register_interests(&[
                ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0x01)),
                    local_matcher: None,
                    route_key: None,
                }),
                ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0x02)),
                    local_matcher: None,
                    route_key: None,
                }),
                ReactiveInterest::PendingTransactions(PendingTxInterest::default()),
            ])
            .await
            .expect("register base interests");

        // The two default-block-option log filters merge into one address
        // superset (existing consolidation behavior), so there is one log source
        // — assigned id 0, before the pending-hash source.
        let sources = subscriber.stream_sources().expect("stream sources");
        assert_eq!(sources.len(), 2);
        assert!(matches!(
            &sources[0],
            SubscriberStreamSource::PubSubLog { id: 0, .. }
        ));
        assert!(matches!(
            sources[1],
            SubscriberStreamSource::PubSubPendingHashes
        ));

        // Ids are stable across repeated source construction.
        let again = subscriber.stream_sources().expect("stream sources again");
        assert!(again[0].same_key(&sources[0]));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn pubsub_stream_termination_attempts_reconnect_before_error() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig {
                reconnect: SubscriberReconnectConfig {
                    initial_delay: Duration::ZERO,
                    retry_delay: Duration::ZERO,
                    max_delay: Duration::ZERO,
                    max_attempts: Some(1),
                    ..SubscriberReconnectConfig::default()
                },
                ..SubscriberConfig::default()
            },
        );
        subscriber.chain_id = Some(1);
        subscriber.interests = vec![ReactiveInterest::PendingTransactions(
            PendingTxInterest::default(),
        )];

        let mut streams = SubscriberStreams::new();
        let source = SubscriberStreamSource::PubSubPendingHashes;
        streams.push(
            source,
            stream::once(async {
                SubscriberEvent::<Ethereum>::StreamTerminated(
                    SubscriberStreamSource::PubSubPendingHashes,
                )
            })
            .boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);

        let result = subscriber.next_batch().await;
        assert!(
            matches!(result, Err(SubscriberError::Provider(ref message)) if message.contains("reconnect failed after 1 attempt")),
            "terminated pubsub streams should attempt reconnect before surfacing failure: {result:?}"
        );
    }

    #[test]
    fn backfilled_logs_skip_recent_subscription_duplicates() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.interests = vec![ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new()
                .address(Address::repeat_byte(0x42))
                .event_signature(B256::repeat_byte(0x01)),
            local_matcher: None,
            route_key: None,
        })];

        let log = rpc_log(false);
        subscriber.enqueue_event(SubscriberEvent::Log {
            source_id: 0,
            log: log.clone(),
        });
        subscriber.enqueue_event(SubscriberEvent::BackfilledLogs {
            source_id: 0,
            logs: vec![log],
        });

        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(subscriber.last_seen_log_blocks.get(&0), Some(&7));
        assert_eq!(
            subscriber.pending_records[0].context.source,
            InputSource::Subscription
        );
    }

    #[test]
    fn backfilled_logs_surface_with_backfill_source() {
        // A backfilled log with no prior subscription duplicate is delivered as
        // an `InputSource::Backfill` record (the positive side of the dedup test,
        // pinning the README's "marking recovered records as InputSource::Backfill"
        // claim — the only place that source is produced).
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.interests = vec![ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new()
                .address(Address::repeat_byte(0x42))
                .event_signature(B256::repeat_byte(0x01)),
            local_matcher: None,
            route_key: None,
        })];

        subscriber.enqueue_event(SubscriberEvent::BackfilledLogs {
            source_id: 0,
            logs: vec![rpc_log(false)],
        });

        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(
            subscriber.pending_records[0].context.source,
            InputSource::Backfill
        );
        assert_eq!(subscriber.last_seen_log_blocks.get(&0), Some(&7));
    }

    #[test]
    #[cfg(feature = "reactive-ws")]
    fn owner_removal_preserves_delivery_and_dedupe_state() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(
                HandlerId::new("pool-a"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new()
                        .address(Address::repeat_byte(0x42))
                        .event_signature(B256::repeat_byte(0x01)),
                    local_matcher: None,
                    route_key: None,
                })],
            )
            .expect("register pool-a owner");
        subscriber
            .add_interest_owner(
                HandlerId::new("pool-b"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new()
                        .address(Address::repeat_byte(0x24))
                        .event_signature(B256::repeat_byte(0x02)),
                    local_matcher: None,
                    route_key: None,
                })],
            )
            .expect("register pool-b owner");

        // Allocate source ids the way live stream setup would (pool-a -> id 0),
        // so the injected delivery anchor hangs off a referenced filter.
        let sources = subscriber.stream_sources().expect("stream sources");
        subscriber.enqueue_event(SubscriberEvent::Log {
            source_id: 0,
            log: rpc_log(false),
        });
        let mut streams = SubscriberStreams::new();
        streams.push(
            sources[0].clone(),
            stream::pending::<SubscriberEvent<Ethereum>>().boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);
        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(subscriber.recent_input_refs.len(), 1);
        assert_eq!(subscriber.last_seen_log_blocks.get(&0), Some(&7));

        let removed = subscriber
            .remove_interest_owner(&HandlerId::new("pool-b"))
            .expect("pool-b should be removed");

        assert_eq!(removed.len(), 1);
        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(subscriber.recent_input_refs.len(), 1);
        assert_eq!(subscriber.last_seen_log_blocks.get(&0), Some(&7));
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("pool-a"))
                .is_some()
        );
        assert!(
            subscriber
                .owner_interests(&HandlerId::new("pool-b"))
                .is_none()
        );
        assert_eq!(subscriber.registered_interests().len(), 1);
    }

    #[test]
    #[cfg(feature = "reactive-ws")]
    fn owner_log_sources_fan_in_across_owners() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(
                HandlerId::new("pool-a"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0xa1)),
                    local_matcher: None,
                    route_key: None,
                })],
            )
            .expect("register pool-a owner");

        let initial_sources = subscriber.stream_sources().expect("initial sources");
        assert_eq!(initial_sources.len(), 1);
        let pool_a_source = initial_sources[0].clone();
        assert!(matches!(
            &pool_a_source,
            SubscriberStreamSource::PubSubLog { id: 0, .. }
        ));

        subscriber
            .add_interest_owner(
                HandlerId::new("pool-b"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new().address(Address::repeat_byte(0xb2)),
                    local_matcher: None,
                    route_key: None,
                })],
            )
            .expect("register pool-b owner");

        let expanded_sources = subscriber.stream_sources().expect("expanded sources");
        assert_eq!(
            expanded_sources.len(),
            1,
            "compatible owner filters should share one provider subscription"
        );
        assert!(
            !expanded_sources[0].same_key(&pool_a_source),
            "the provider-facing superset changes while owner routing remains exact"
        );

        subscriber
            .remove_interest_owner(&HandlerId::new("pool-b"))
            .expect("pool-b should be removed");
        let trimmed_sources = subscriber.stream_sources().expect("trimmed sources");
        assert_eq!(trimmed_sources.len(), 1);
        assert!(trimmed_sources[0].same_key(&pool_a_source));
    }

    #[test]
    #[cfg(feature = "reactive-ws")]
    fn provider_log_fan_in_respects_address_ceiling() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig {
                max_log_addresses_per_subscription: 2,
                ..SubscriberConfig::default()
            },
        );
        for index in 0..5 {
            subscriber
                .add_interest_owner(
                    HandlerId::new(format!("pool-{index}")),
                    &[log_interest_for(index + 1)],
                )
                .expect("register pool owner");
        }

        let sources = subscriber.stream_sources().expect("stream sources");
        assert_eq!(sources.len(), 3);
        let mut address_counts: Vec<_> = sources
            .iter()
            .map(|source| match source {
                SubscriberStreamSource::PubSubLog { filter, .. } => filter.address.iter().count(),
                _ => panic!("expected log source"),
            })
            .collect();
        address_counts.sort_unstable();
        assert_eq!(address_counts, vec![1, 2, 2]);
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn owner_backfill_seeds_reconnect_anchor_before_live_log() {
        let asserter = Asserter::new();
        asserter.push_success(&Some(rpc_block(7, B256::repeat_byte(0x02))));
        asserter.push_success(&vec![rpc_log(false)]);
        asserter.push_success(&Some(rpc_block(7, B256::repeat_byte(0x02))));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("pool-a"),
                &[ReactiveInterest::Logs(LogInterest {
                    provider_filter: Filter::new()
                        .address(Address::repeat_byte(0x42))
                        .event_signature(B256::repeat_byte(0x01)),
                    local_matcher: None,
                    route_key: None,
                })],
                SubscriberBackfill::range(1, 7),
            )
            .expect("register pool-a with backfill");

        subscriber
            .drain_pending_backfills()
            .await
            .expect("owner backfill should drain");

        assert_eq!(subscriber.pending_records.len(), 1);
        assert_eq!(subscriber.last_seen_log_blocks.get(&0), Some(&7));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn subscriber_streams_poll_ready_sources_round_robin() {
        let first_hash = B256::repeat_byte(0x01);
        let second_hash = B256::repeat_byte(0x02);
        let mut streams = SubscriberStreams::new();
        streams.push(
            SubscriberStreamSource::PubSubPendingHashes,
            stream::iter([
                SubscriberEvent::<Ethereum>::PendingHash(first_hash),
                SubscriberEvent::<Ethereum>::PendingHash(first_hash),
            ])
            .boxed(),
        );
        streams.push(
            SubscriberStreamSource::PubSubBlockHeaders,
            stream::once(async move { SubscriberEvent::<Ethereum>::PendingHash(second_hash) })
                .boxed(),
        );

        assert!(matches!(
            streams.next().await,
            Some(SubscriberEvent::PendingHash(hash)) if hash == first_hash
        ));
        assert!(matches!(
            streams.next().await,
            Some(SubscriberEvent::PendingHash(hash)) if hash == second_hash
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn owner_updates_ensure_streams_without_full_reset() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        subscriber
            .register_interests(&[ReactiveInterest::PendingTransactions(
                PendingTxInterest::default(),
            )])
            .await
            .expect("register base pending interest");
        subscriber
            .add_interest_owner(
                HandlerId::new("headers"),
                &[ReactiveInterest::Blocks(BlockInterest::default())],
            )
            .expect("register header owner");

        let mut streams = SubscriberStreams::new();
        streams.push(
            SubscriberStreamSource::PubSubPendingHashes,
            stream::pending::<SubscriberEvent<Ethereum>>().boxed(),
        );
        streams.push(
            SubscriberStreamSource::PubSubBlockHeaders,
            stream::pending::<SubscriberEvent<Ethereum>>().boxed(),
        );
        subscriber.state = AlloySubscriberState::Active(streams);

        subscriber
            .remove_interest_owner(&HandlerId::new("headers"))
            .expect("header owner should be removed");
        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams) if streams.len() == 2
        ));

        subscriber
            .ensure_streams()
            .await
            .expect("pure removal reconciliation should not touch provider");

        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams)
                if streams.len() == 1
                    && streams.contains_source(&SubscriberStreamSource::PubSubPendingHashes)
                    && !streams.contains_source(&SubscriberStreamSource::PubSubBlockHeaders)
        ));

        subscriber
            .add_interest_owner(
                HandlerId::new("headers"),
                &[ReactiveInterest::Blocks(BlockInterest::default())],
            )
            .expect("re-add header owner");
        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams) if streams.len() == 1
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-polling")]
    async fn ensure_streams_retains_each_successful_connection_across_later_failure() {
        let asserter = Asserter::new();
        asserter.push_success(&U256::from(1));
        asserter.push_failure_msg("second filter connection failed");
        let provider = ProviderBuilder::new().connect_mocked_client(asserter.clone());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::Polling,
            SubscriberConfig {
                max_log_addresses_per_subscription: 1,
                ..SubscriberConfig::default()
            },
        );
        subscriber.chain_id = Some(1);
        subscriber
            .register_interests(&[log_interest_for(0x41), log_interest_for(0x42)])
            .await
            .expect("register two independently connected filters");

        let error = subscriber
            .ensure_streams()
            .await
            .expect_err("second provider connection is forced to fail");
        assert!(matches!(error, SubscriberError::Provider(_)));
        assert!(subscriber.sources_dirty);
        let retained_streams = match &subscriber.state {
            AlloySubscriberState::Active(streams) => Some(streams.len()),
            AlloySubscriberState::Uninitialized | AlloySubscriberState::Empty => None,
        };
        assert_eq!(
            retained_streams,
            Some(1),
            "first connection must survive later error {error:?}; revision {}",
            subscriber.stream_revision
        );

        asserter.push_success(&U256::from(2));
        subscriber
            .ensure_streams()
            .await
            .expect("retry connects only the missing source");
        assert!(!subscriber.sources_dirty);
        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams) if streams.len() == 2
        ));
        assert!(asserter.read_q().is_empty());
    }

    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn cancelled_post_install_backfill_is_retried_without_reconnecting() {
        let asserter = Asserter::new();
        let provider = ProviderBuilder::new().connect_mocked_client(asserter.clone());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber.chain_id = Some(1);
        subscriber
            .register_interests(&[log_interest_for(0x43)])
            .await
            .expect("register log source");
        let source = subscriber
            .stream_sources()
            .expect("one desired source")
            .pop()
            .expect("log source");
        let SubscriberStreamSource::PubSubLog { id, .. } = source else {
            panic!("expected pubsub log source")
        };
        subscriber.last_seen_log_blocks.insert(id, 6);

        {
            let source = SubscriberStreamSource::PubSubLog {
                id,
                filter: subscriber
                    .log_stream_filters()
                    .pop()
                    .expect("provider filter"),
            };
            let interrupted = async {
                subscriber.install_source_stream(
                    source.clone(),
                    stream::pending::<SubscriberEvent<Ethereum>>().boxed(),
                );
                subscriber.queue_source_backfill(source);
                subscriber.sources_dirty = true;
                futures::future::pending::<()>().await;
            };
            futures::pin_mut!(interrupted);
            poll_fn(|cx| {
                assert!(interrupted.as_mut().poll(cx).is_pending());
                std::task::Poll::Ready(())
            })
            .await;
        }

        assert_eq!(subscriber.pending_source_backfills.len(), 1);
        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams) if streams.len() == 1
        ));

        asserter.push_success(&7u64);
        asserter.push_success(&Vec::<Log>::new());
        subscriber
            .ensure_streams()
            .await
            .expect("retry completes only the pending historical window");

        assert!(subscriber.pending_source_backfills.is_empty());
        assert!(!subscriber.sources_dirty);
        assert!(matches!(
            &subscriber.state,
            AlloySubscriberState::Active(streams) if streams.len() == 1
        ));
        assert!(asserter.read_q().is_empty());
    }

    // A log interest matching `rpc_log` (address 0x42, topic0 0x01).
    #[cfg(feature = "reactive-ws")]
    fn log_interest_matching_rpc_log() -> ReactiveInterest<Ethereum> {
        ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new()
                .address(Address::repeat_byte(0x42))
                .event_signature(B256::repeat_byte(0x01)),
            local_matcher: None,
            route_key: None,
        })
    }

    #[cfg(any(feature = "reactive-ws", feature = "reactive-polling"))]
    fn log_interest_for(address: u8) -> ReactiveInterest<Ethereum> {
        ReactiveInterest::Logs(LogInterest {
            provider_filter: Filter::new().address(Address::repeat_byte(address)),
            local_matcher: None,
            route_key: None,
        })
    }

    // B1: a transient provider error must not consume the queued backfill — the
    // missed window has to survive for the next poll to retry.
    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn drain_backfill_retains_queue_entry_on_provider_error() {
        let asserter = Asserter::new();
        asserter.push_failure_msg("rate limited");
        asserter.push_success(&Some(rpc_block(7, B256::repeat_byte(0x02))));
        asserter.push_success(&vec![rpc_log(false)]);
        asserter.push_success(&Some(rpc_block(7, B256::repeat_byte(0x02))));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("pool"),
                &[log_interest_matching_rpc_log()],
                SubscriberBackfill::range(1, 7),
            )
            .expect("register owner with backfill");
        assert_eq!(subscriber.pending_backfills.len(), 1);

        let first = subscriber.drain_pending_backfills().await;
        assert!(first.is_err(), "provider failure should surface");
        assert_eq!(
            subscriber.pending_backfills.len(),
            1,
            "failed fetch must leave the backfill queued for retry"
        );
        assert!(subscriber.pending_records.is_empty());

        subscriber
            .drain_pending_backfills()
            .await
            .expect("retry should succeed");
        assert!(subscriber.pending_backfills.is_empty());
        assert_eq!(subscriber.pending_records.len(), 1);
    }

    // B3: a zero-log backfill window still advances the delivery anchor to its
    // upper bound, so a later reconnect catches up from the right block.
    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn drain_backfill_seeds_anchor_on_empty_window() {
        let asserter = Asserter::new();
        asserter.push_success(&Some(rpc_block(42, B256::repeat_byte(42))));
        asserter.push_success(&Vec::<Log>::new());
        asserter.push_success(&Some(rpc_block(42, B256::repeat_byte(42))));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("pool"),
                &[log_interest_matching_rpc_log()],
                SubscriberBackfill::range(1, 42),
            )
            .expect("register owner with backfill");

        subscriber
            .drain_pending_backfills()
            .await
            .expect("empty backfill should drain");

        assert!(subscriber.pending_records.is_empty());
        let filter = log_filters(subscriber.owner_interests(&HandlerId::new("pool")).unwrap())
            .pop()
            .unwrap();
        assert_eq!(
            subscriber.log_anchor(&filter),
            Some(42),
            "empty window must still seed the anchor at its upper bound"
        );
    }

    // B3 (open-ended): a `from_block`-only backfill resolves its upper bound to
    // the provider head and seeds the anchor there.
    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn drain_backfill_open_ended_resolves_head_and_seeds_anchor() {
        let asserter = Asserter::new();
        asserter.push_success(&100u64); // get_block_number
        asserter.push_success(&Some(rpc_block(100, B256::repeat_byte(100))));
        asserter.push_success(&Vec::<Log>::new()); // get_logs
        asserter.push_success(&Some(rpc_block(100, B256::repeat_byte(100))));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let mut subscriber = AlloySubscriber::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("pool"),
                &[log_interest_matching_rpc_log()],
                SubscriberBackfill::from_block(10),
            )
            .expect("register owner with open-ended backfill");

        subscriber
            .drain_pending_backfills()
            .await
            .expect("open-ended backfill should drain");

        let filter = log_filters(subscriber.owner_interests(&HandlerId::new("pool")).unwrap())
            .pop()
            .unwrap();
        assert_eq!(subscriber.log_anchor(&filter), Some(100));
    }

    // B2: two owners requesting the same filter shape share exactly one live
    // source (and thus one anchor), rather than double-subscribing.
    #[test]
    #[cfg(feature = "reactive-ws")]
    fn duplicate_filters_across_owners_map_to_single_source() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(HandlerId::new("pool-a"), &[log_interest_for(0xaa)])
            .expect("register pool-a");
        subscriber
            .add_interest_owner(HandlerId::new("pool-b"), &[log_interest_for(0xaa)])
            .expect("register pool-b with identical filter");

        assert_eq!(
            subscriber.log_stream_filters().len(),
            1,
            "identical filters across owners must collapse to one"
        );
        let sources = subscriber.stream_sources().expect("stream sources");
        assert_eq!(sources.len(), 1);
    }

    // B4: removing an owner retires the source-id and anchor bookkeeping for
    // filters no other owner references, so long-lived churn cannot leak.
    #[test]
    #[cfg(feature = "reactive-ws")]
    fn owner_removal_prunes_source_ids_and_anchors() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(HandlerId::new("pool-a"), &[log_interest_for(0xaa)])
            .expect("register pool-a");
        subscriber
            .add_interest_owner(HandlerId::new("pool-b"), &[log_interest_for(0xbb)])
            .expect("register pool-b");

        // Allocate ids and simulate delivery anchors on both.
        let _ = subscriber.stream_sources().expect("stream sources");
        let filter_a = log_filters(&[log_interest_for(0xaa)]).pop().unwrap();
        let filter_b = log_filters(&[log_interest_for(0xbb)]).pop().unwrap();
        let id_a = subscriber.log_source_id(&filter_a);
        let id_b = subscriber.log_source_id(&filter_b);
        subscriber.last_seen_log_blocks.insert(id_a, 10);
        subscriber.last_seen_log_blocks.insert(id_b, 20);
        assert_eq!(
            subscriber.log_source_ids.len(),
            3,
            "one provider fan-in id plus two explicitly seeded logical ids"
        );

        subscriber
            .remove_interest_owner(&HandlerId::new("pool-b"))
            .expect("remove pool-b");

        assert_eq!(
            subscriber.log_source_ids.len(),
            1,
            "pool-b's filter id should be retired"
        );
        assert!(subscriber.log_source_ids.contains_key(&filter_a));
        assert_eq!(subscriber.last_seen_log_blocks.get(&id_a), Some(&10));
        assert_eq!(
            subscriber.last_seen_log_blocks.get(&id_b),
            None,
            "pool-b's anchor should be pruned"
        );
    }

    // D1: growing an owner's filter set (a new pool on an existing adapter)
    // changes the merged filter shape; the new shape must inherit the old
    // anchor via an automatic continuity backfill, or logs between the last
    // delivery and the new subscription are silently lost.
    #[test]
    #[cfg(feature = "reactive-ws")]
    fn owner_filter_growth_queues_continuity_backfill_from_prior_anchor() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(HandlerId::new("amm"), &[log_interest_for(0xaa)])
            .expect("register amm with pool A");

        // Simulate the owner's single merged filter having delivered up to
        // block 50.
        let filter_a = log_filters(&[log_interest_for(0xaa)]).pop().unwrap();
        let id_a = subscriber.log_source_id(&filter_a);
        subscriber.last_seen_log_blocks.insert(id_a, 50);

        // Grow the owner to also watch pool B (same block option -> merges into
        // one {A,B} filter, a new shape).
        subscriber
            .add_interest_owner(
                HandlerId::new("amm"),
                &[log_interest_for(0xaa), log_interest_for(0xbb)],
            )
            .expect("grow amm to pools A+B");

        assert_eq!(
            subscriber.pending_backfills.len(),
            1,
            "the changed merged filter should queue exactly one continuity backfill"
        );
        let queued = &subscriber.pending_backfills[0];
        assert_eq!(queued.owner, Some(HandlerId::new("amm")));
        assert_eq!(queued.backfill.start_block(), 50);
        assert_eq!(
            queued.backfill.end_block(),
            None,
            "continuity backfill runs open-ended to the current head"
        );
    }

    // D1 negative: replacing an owner's interests with the identical shape must
    // NOT re-fetch — the filter kept its anchor and its live stream.
    #[test]
    #[cfg(feature = "reactive-ws")]
    fn unchanged_owner_filter_does_not_queue_continuity_backfill() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(HandlerId::new("amm"), &[log_interest_for(0xaa)])
            .expect("register amm");
        let filter_a = log_filters(&[log_interest_for(0xaa)]).pop().unwrap();
        let id_a = subscriber.log_source_id(&filter_a);
        subscriber.last_seen_log_blocks.insert(id_a, 50);

        subscriber
            .add_interest_owner(HandlerId::new("amm"), &[log_interest_for(0xaa)])
            .expect("re-register identical interests");

        assert!(
            subscriber.pending_backfills.is_empty(),
            "an unchanged filter shape must not queue continuity backfill"
        );
    }

    // D5 interaction: an explicit open-ended backfill starting at or below the
    // owner's prior anchor already covers the continuity window, so no extra
    // continuity backfill is queued (no redundant double fetch).
    #[test]
    #[cfg(feature = "reactive-ws")]
    fn explicit_open_ended_backfill_below_anchor_suppresses_continuity() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        subscriber
            .add_interest_owner(HandlerId::new("amm"), &[log_interest_for(0xaa)])
            .expect("register amm");
        let filter_a = log_filters(&[log_interest_for(0xaa)]).pop().unwrap();
        let id_a = subscriber.log_source_id(&filter_a);
        subscriber.last_seen_log_blocks.insert(id_a, 50);

        // Grow with an explicit deep backfill from block 10 (< anchor 50).
        subscriber
            .add_interest_owner_with_backfill(
                HandlerId::new("amm"),
                &[log_interest_for(0xaa), log_interest_for(0xbb)],
                SubscriberBackfill::from_block(10),
            )
            .expect("grow amm with explicit deep backfill");

        assert_eq!(
            subscriber.pending_backfills.len(),
            1,
            "only the explicit backfill should be queued; continuity is subsumed"
        );
        assert_eq!(subscriber.pending_backfills[0].backfill.start_block(), 10);
    }

    // The dirty flag gates reconciliation: when nothing changed since the last
    // reconcile, `ensure_streams` must not touch the provider or the state.
    #[tokio::test(flavor = "multi_thread")]
    #[cfg(feature = "reactive-ws")]
    async fn ensure_streams_is_noop_when_not_dirty() {
        let provider = ProviderBuilder::new().connect_mocked_client(Asserter::new());
        let mut subscriber = AlloySubscriber::<_, Ethereum>::new(
            provider,
            SubscriberMode::PubSub,
            SubscriberConfig::default(),
        );
        // An interest that WOULD require a new block-header source...
        subscriber
            .add_interest_owner(
                HandlerId::new("headers"),
                &[ReactiveInterest::Blocks(BlockInterest::default())],
            )
            .expect("register header owner");
        // ...but we mark bookkeeping clean and start from Empty.
        subscriber.state = AlloySubscriberState::Empty;
        subscriber.sources_dirty = false;

        subscriber
            .ensure_streams()
            .await
            .expect("clean reconcile must be a no-op");

        assert!(
            matches!(subscriber.state, AlloySubscriberState::Empty),
            "not-dirty ensure_streams must not connect new sources"
        );
    }
}

fn resolve_subscriber_transport(
    mode: SubscriberMode,
) -> Result<SubscriberTransport, SubscriberError> {
    match mode {
        SubscriberMode::PubSub => {
            #[cfg(feature = "reactive-ws")]
            {
                Ok(SubscriberTransport::PubSub)
            }
            #[cfg(not(feature = "reactive-ws"))]
            {
                Err(SubscriberError::Unsupported(
                    "AlloySubscriber pubsub mode requires the reactive-ws feature",
                ))
            }
        }
        SubscriberMode::Polling => {
            #[cfg(feature = "reactive-polling")]
            {
                Ok(SubscriberTransport::Polling)
            }
            #[cfg(not(feature = "reactive-polling"))]
            {
                Err(SubscriberError::Unsupported(
                    "AlloySubscriber polling mode requires the reactive-polling feature",
                ))
            }
        }
        SubscriberMode::Auto => resolve_auto_subscriber_transport(),
    }
}

fn resolve_auto_subscriber_transport() -> Result<SubscriberTransport, SubscriberError> {
    #[cfg(feature = "reactive-ws")]
    {
        Ok(SubscriberTransport::PubSub)
    }

    #[cfg(all(not(feature = "reactive-ws"), feature = "reactive-polling"))]
    {
        Ok(SubscriberTransport::Polling)
    }

    #[cfg(not(any(feature = "reactive-ws", feature = "reactive-polling")))]
    {
        Err(SubscriberError::Unsupported(
            "AlloySubscriber requires either reactive-ws or reactive-polling",
        ))
    }
}

fn validate_subscriber_config(config: &SubscriberConfig) -> Result<(), SubscriberError> {
    if config.preconfirmations != PreconfirmationMode::Disabled
        && config.flashblock_poll_interval.is_zero()
    {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::flashblock_poll_interval must be greater than zero",
        ));
    }
    if config.max_batch_size == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_batch_size must be greater than zero",
        ));
    }
    if config.max_log_addresses_per_subscription == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_log_addresses_per_subscription must be greater than zero",
        ));
    }
    if config.max_pending_records == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_pending_records must be greater than zero",
        ));
    }
    if config.max_pending_backfills == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_pending_backfills must be greater than zero",
        ));
    }
    if config.max_backfill_log_bytes == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_backfill_log_bytes must be greater than zero",
        ));
    }
    if config.max_reconcile_requests_in_flight == 0 {
        return Err(SubscriberError::InvalidConfig(
            "SubscriberConfig::max_reconcile_requests_in_flight must be greater than zero",
        ));
    }
    if config.reconnect.enabled {
        if config.reconnect.retry_delay > config.reconnect.max_delay {
            return Err(SubscriberError::InvalidConfig(
                "SubscriberReconnectConfig::retry_delay must be less than or equal to max_delay",
            ));
        }
        if matches!(config.reconnect.max_attempts, Some(0)) {
            return Err(SubscriberError::InvalidConfig(
                "SubscriberReconnectConfig::max_attempts must be greater than zero when set",
            ));
        }
    }
    Ok(())
}

fn validate_supported_interests<N: Network>(
    mode: SubscriberMode,
    config: &SubscriberConfig,
    interests: &[ReactiveInterest<N>],
) -> Result<(), SubscriberError> {
    let transport = resolve_subscriber_transport(mode)?;

    for interest in interests {
        match interest {
            ReactiveInterest::Logs(_) => {}
            ReactiveInterest::PendingTransactions(interest)
                if !config.hydrate_pending_transactions && interest.matches_hash_only() => {}
            ReactiveInterest::PendingTransactions(_) => {
                return Err(SubscriberError::Unsupported(
                    "AlloySubscriber currently supports pending transaction hash interests only (full pending-tx hydration is unimplemented)",
                ));
            }
            ReactiveInterest::Blocks(interest) => match (transport, interest.mode) {
                (SubscriberTransport::PubSub, BlockInterestMode::Header) => {}
                (_, BlockInterestMode::FullBlock) => {
                    return Err(SubscriberError::Unsupported(
                        "AlloySubscriber full block streams are not implemented in this transport slice",
                    ));
                }
                (SubscriberTransport::Polling, BlockInterestMode::Header) => {
                    return Err(SubscriberError::Unsupported(
                        "AlloySubscriber polling block streams are not implemented in this transport slice",
                    ));
                }
            },
        }
    }

    Ok(())
}

fn log_filters<N: Network>(interests: &[ReactiveInterest<N>]) -> Vec<Filter> {
    let mut filters = Vec::new();
    for interest in interests {
        if let ReactiveInterest::Logs(interest) = interest {
            merge_log_subscription_filter(&mut filters, &interest.provider_filter);
        }
    }
    filters
}

fn needs_header_block_stream<N: Network>(interests: &[ReactiveInterest<N>]) -> bool {
    interests.iter().any(|interest| {
        matches!(
            interest,
            ReactiveInterest::Blocks(BlockInterest {
                mode: BlockInterestMode::Header,
            })
        )
    })
}

fn needs_pending_hash_stream<N: Network>(interests: &[ReactiveInterest<N>]) -> bool {
    interests.iter().any(|interest| {
        matches!(
            interest,
            ReactiveInterest::PendingTransactions(interest) if interest.matches_hash_only()
        )
    })
}

fn log_matches_any_interest<N: Network>(log: &Log, interests: &[ReactiveInterest<N>]) -> bool {
    interests.iter().any(|interest| {
        matches!(
            interest,
            ReactiveInterest::Logs(interest) if interest.matches(log)
        )
    })
}

fn validate_owner_backfill_logs(
    logs: &[Log],
    from_block: u64,
    through: &BlockRef,
) -> Result<(), SubscriberOwnerError> {
    for log in logs {
        if log.removed {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "removed log in canonical catch-up",
            ));
        }
        let number = log
            .block_number
            .ok_or(SubscriberOwnerError::InvalidBackfillLog(
                "log missing block number",
            ))?;
        let hash = log
            .block_hash
            .ok_or(SubscriberOwnerError::InvalidBackfillLog(
                "log missing block hash",
            ))?;
        log.transaction_hash
            .ok_or(SubscriberOwnerError::InvalidBackfillLog(
                "log missing transaction hash",
            ))?;
        log.transaction_index
            .ok_or(SubscriberOwnerError::InvalidBackfillLog(
                "log missing transaction index",
            ))?;
        log.log_index
            .ok_or(SubscriberOwnerError::InvalidBackfillLog(
                "log missing log index",
            ))?;
        if number < from_block || number > through.number {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "log outside requested block range",
            ));
        }
        if number == through.number && hash != through.hash {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "target-block log hash mismatch",
            ));
        }
    }
    Ok(())
}

fn validate_backfill_resource_limits(
    logs: &[Log],
    max_logs: usize,
    max_log_bytes: usize,
) -> Result<usize, SubscriberError> {
    if logs.len() > max_logs {
        return Err(SubscriberError::ResourceExhausted(format!(
            "historical response returned {} logs, above the configured limit of {max_logs}",
            logs.len()
        )));
    }
    let bytes = logs.iter().fold(0usize, |total, log| {
        // Include fixed address/block/transaction/index fields in addition to
        // the variable topic and data payload. This is deliberately a stable
        // conservative accounting unit rather than Rust heap-layout size.
        let fixed = 20usize + (32 * 3) + (8 * 4) + 1;
        total
            .saturating_add(fixed)
            .saturating_add(log.topics().len().saturating_mul(32))
            .saturating_add(log.inner.data.data.len())
    });
    if bytes > max_log_bytes {
        return Err(SubscriberError::ResourceExhausted(format!(
            "historical response retained approximately {bytes} log bytes, above the configured limit of {max_log_bytes}"
        )));
    }
    Ok(bytes)
}

async fn fetch_provider_block_ref<P, N>(
    provider: &P,
    number: u64,
) -> Result<BlockRef, SubscriberError>
where
    P: Provider<N> + Send + Sync,
    N: Network,
{
    let block = provider
        .get_block_by_number(BlockNumberOrTag::Number(number))
        .await
        .map_err(provider_error)?
        .ok_or_else(|| {
            SubscriberError::InvalidBackfill(format!(
                "canonical target block {number} is unavailable"
            ))
        })?;
    let header = block.header();
    Ok(BlockRef {
        number: header.number(),
        hash: header.hash(),
        parent_hash: Some(header.parent_hash()),
        timestamp: Some(header.timestamp()),
    })
}

fn block_ref_satisfies_expected(actual: &BlockRef, expected: &BlockRef) -> bool {
    actual.number == expected.number
        && actual.hash == expected.hash
        && optional_metadata_compatible(actual.parent_hash.as_ref(), expected.parent_hash.as_ref())
        && optional_metadata_compatible(actual.timestamp.as_ref(), expected.timestamp.as_ref())
}

fn validate_owner_backfill_log_set(logs: &[Log]) -> Result<(), SubscriberOwnerError> {
    let mut positions = HashMap::new();
    let mut block_hashes = HashMap::new();
    let mut transaction_hashes = HashMap::new();
    let mut transaction_positions = HashMap::new();
    let mut ordering = BTreeMap::<u64, Vec<(u64, u64)>>::new();
    for log in logs {
        let number = log
            .block_number
            .expect("individual owner catch-up logs are validated before set validation");
        let block_hash = log
            .block_hash
            .expect("individual owner catch-up logs are validated before set validation");
        let transaction_hash = log
            .transaction_hash
            .expect("individual owner catch-up logs are validated before set validation");
        let transaction_index = log
            .transaction_index
            .expect("individual owner catch-up logs are validated before set validation");
        let log_index = log
            .log_index
            .expect("individual owner catch-up logs are validated before set validation");
        if block_hashes
            .insert(number, block_hash)
            .is_some_and(|prior| prior != block_hash)
        {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "conflicting block identity in canonical catch-up",
            ));
        }
        if let Some(previous) = positions.insert((number, log_index), log)
            && previous != log
        {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "conflicting logs at one canonical block position",
            ));
        }
        let conflicting_transaction = transaction_hashes
            .insert((number, transaction_index), transaction_hash)
            .is_some_and(|prior| prior != transaction_hash)
            || transaction_positions
                .insert((number, transaction_hash), transaction_index)
                .is_some_and(|prior| prior != transaction_index);
        if conflicting_transaction {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "conflicting transaction identity at one canonical block position",
            ));
        }
        ordering
            .entry(number)
            .or_default()
            .push((log_index, transaction_index));
    }
    for positions in ordering.values_mut() {
        positions.sort_unstable();
        if positions.windows(2).any(|pair| pair[0].1 > pair[1].1) {
            return Err(SubscriberOwnerError::InvalidBackfillLog(
                "transaction and log positions disagree on canonical order",
            ));
        }
    }
    Ok(())
}

fn merged_owner_reconcile_filters<N: Network>(
    plans: &[SubscriberOwnerReconcilePlan<N>],
    through: u64,
) -> Vec<SubscriberOwnerReconcileFilter> {
    let mut by_start = BTreeMap::<u64, Vec<Filter>>::new();
    for plan in plans.iter().filter(|plan| plan.from_block <= through) {
        let filters = by_start.entry(plan.from_block).or_default();
        filters.extend(
            log_filters(&plan.interests)
                .into_iter()
                .map(|filter| filter.from_block(plan.from_block).to_block(through)),
        );
    }

    let mut chunks = Vec::new();
    for (from_block, filters) in by_start {
        for filters in filters.chunks(OWNER_RECONCILE_FILTERS_PER_CHUNK) {
            let mut merged = Vec::new();
            for filter in filters {
                merge_log_subscription_filter(&mut merged, filter);
            }
            chunks.extend(
                merged
                    .into_iter()
                    .map(|filter| SubscriberOwnerReconcileFilter { filter, from_block }),
            );
        }
    }
    chunks
}

fn merged_lazy_backfill_filters(
    filters: &[Filter],
    from_block: u64,
    through: u64,
) -> Vec<SubscriberOwnerReconcileFilter> {
    let mut requests = Vec::new();
    for filters in filters.chunks(OWNER_RECONCILE_FILTERS_PER_CHUNK) {
        let mut merged = Vec::new();
        for filter in filters {
            merge_log_subscription_filter(
                &mut merged,
                &filter.clone().from_block(from_block).to_block(through),
            );
        }
        requests.extend(
            merged
                .into_iter()
                .map(|filter| SubscriberOwnerReconcileFilter { filter, from_block }),
        );
    }
    requests
}

fn lazy_backfill_error(error: SubscriberOwnerError) -> SubscriberError {
    match error {
        SubscriberOwnerError::Subscriber(error) => error,
        error => SubscriberError::InvalidBackfill(error.to_string()),
    }
}

fn global_backfill_barrier(backfill: SubscriberBackfill, certified: BlockRef) -> ChainControl {
    let mut id = b"alloy-global-backfill-v1".to_vec();
    id.extend_from_slice(&backfill.start_block().to_be_bytes());
    id.extend_from_slice(&certified.number.to_be_bytes());
    id.extend_from_slice(certified.hash.as_slice());
    ChainControl::Barrier {
        id,
        block: Some(certified),
    }
}

async fn fetch_owner_catchup<P, N>(
    provider: P,
    filters: Vec<SubscriberOwnerReconcileFilter>,
    retained: Vec<BlockRef>,
    through: BlockRef,
    options: SubscriberOwnerCatchupOptions,
) -> Result<SubscriberOwnerCatchup, SubscriberOwnerError>
where
    P: Provider<N> + Send + Sync,
    N: Network,
{
    if !options.target_preverified {
        let _ = verify_provider_reconcile_target::<P, N>(&provider, &through).await?;
    }
    let mut certified_positions = HashSet::new();
    for position in retained {
        let target_certifies_position = position == through
            || (position.number.checked_add(1) == Some(through.number)
                && through.parent_hash == Some(position.hash));
        if !target_certifies_position && certified_positions.insert(position) {
            let _ = verify_provider_reconcile_target::<P, N>(&provider, &position).await?;
        }
    }
    let mut logs = Vec::new();
    let mut total_log_bytes = 0usize;
    let requests = stream::iter(filters.into_iter().map(|filter| {
        let provider = &provider;
        async move {
            let logs = provider
                .get_logs(&filter.filter)
                .await
                .map_err(provider_error)?;
            Ok::<_, SubscriberOwnerError>((filter.from_block, logs))
        }
    }))
    .buffer_unordered(options.max_requests_in_flight);
    futures::pin_mut!(requests);
    while let Some(result) = requests.next().await {
        let (from_block, fetched) = result?;
        let fetched_bytes =
            validate_backfill_resource_limits(&fetched, options.max_logs, options.max_log_bytes)?;
        validate_owner_backfill_logs(&fetched, from_block, &through)?;
        if logs.len().saturating_add(fetched.len()) > options.max_logs {
            return Err(SubscriberError::ResourceExhausted(format!(
                "bulk reconcile returned more than {} logs",
                options.max_logs
            ))
            .into());
        }
        total_log_bytes = total_log_bytes.saturating_add(fetched_bytes);
        if total_log_bytes > options.max_log_bytes {
            return Err(SubscriberError::ResourceExhausted(format!(
                "bulk reconcile retained approximately {total_log_bytes} log bytes, above the configured limit of {}",
                options.max_log_bytes
            ))
            .into());
        }
        logs.extend(fetched);
    }
    validate_owner_backfill_log_set(&logs)?;
    let certified = verify_provider_reconcile_target::<P, N>(&provider, &through).await?;
    Ok(SubscriberOwnerCatchup { logs, certified })
}

async fn verify_provider_reconcile_target<P, N>(
    provider: &P,
    expected: &BlockRef,
) -> Result<BlockRef, SubscriberOwnerError>
where
    P: Provider<N> + Send + Sync,
    N: Network,
{
    let block = provider
        .get_block_by_number(BlockNumberOrTag::Number(expected.number))
        .await
        .map_err(provider_error)?
        .ok_or(SubscriberOwnerError::BlockUnavailable(expected.number))?;
    let header = block.header();
    let actual = BlockRef {
        number: header.number(),
        hash: header.hash(),
        parent_hash: Some(header.parent_hash()),
        timestamp: Some(header.timestamp()),
    };
    let exact_parent = expected
        .parent_hash
        .is_none_or(|parent| Some(parent) == actual.parent_hash);
    let exact_timestamp = expected
        .timestamp
        .is_none_or(|timestamp| Some(timestamp) == actual.timestamp);
    if actual.number != expected.number
        || actual.hash != expected.hash
        || !exact_parent
        || !exact_timestamp
    {
        return Err(SubscriberOwnerError::BlockMismatch {
            expected_number: expected.number,
            expected_hash: expected.hash,
            actual_number: actual.number,
            actual_hash: actual.hash,
        });
    }
    Ok(actual)
}

fn log_input_record<N: Network>(log: Log, source: InputSource) -> ReactiveInputRecord<N> {
    let context = log_reactive_context(&log);
    ReactiveInputRecord::new(
        ReactiveInput::Log(log),
        ReactiveContext { source, ..context },
    )
}

fn preconfirmed_log_input_record<N: Network>(
    log: Log,
    flashblock: FlashblockRef,
) -> ReactiveInputRecord<N> {
    let block = flashblock.block_ref();
    let provider = flashblock.provider.clone();
    ReactiveInputRecord::new(
        ReactiveInput::Log(log.clone()),
        ReactiveContext {
            chain_id: None,
            source: InputSource::Flashblocks,
            chain_status: ChainStatus::Preconfirmed { flashblock },
            block: Some(block),
            transaction_index: log.transaction_index,
            log_index: log.log_index,
        },
    )
    .with_provider(provider)
}

fn log_reactive_context(log: &Log) -> ReactiveContext {
    let block = match (log.block_hash, log.block_number) {
        (Some(hash), Some(number)) => Some(BlockRef {
            number,
            hash,
            parent_hash: None,
            timestamp: log.block_timestamp,
        }),
        _ => None,
    };

    let chain_status = match (&block, log.removed) {
        (Some(block), true) => ChainStatus::Reorged {
            dropped_from: *block,
        },
        (Some(block), false) => ChainStatus::Included {
            block: *block,
            confirmations: 0,
        },
        (None, _) => ChainStatus::Pending,
    };

    ReactiveContext {
        chain_id: None,
        source: InputSource::Poll,
        chain_status,
        block,
        transaction_index: log.transaction_index,
        log_index: log.log_index,
    }
}

fn block_header_input_record<N>(header: N::HeaderResponse) -> ReactiveInputRecord<N>
where
    N: Network,
{
    let block = BlockRef {
        number: header.number(),
        hash: HeaderResponseTrait::hash(&header),
        parent_hash: Some(header.parent_hash()),
        timestamp: Some(header.timestamp()),
    };
    ReactiveInputRecord::new(
        ReactiveInput::BlockHeader(header),
        ReactiveContext {
            chain_id: None,
            source: InputSource::Subscription,
            chain_status: ChainStatus::Included {
                block,
                confirmations: 0,
            },
            block: Some(block),
            transaction_index: None,
            log_index: None,
        },
    )
}

fn pending_hash_input_record<N: Network>(
    hash: B256,
    source: InputSource,
) -> ReactiveInputRecord<N> {
    ReactiveInputRecord::new(
        ReactiveInput::PendingTxHash(hash),
        ReactiveContext {
            chain_id: None,
            source,
            chain_status: ChainStatus::Pending,
            block: None,
            transaction_index: None,
            log_index: None,
        },
    )
}

#[cfg(feature = "reactive-ws")]
fn base_pending_log_filter(filter: &Filter) -> Result<serde_json::Value, SubscriberError> {
    let encoded = serde_json::to_value(filter)
        .map_err(|error| SubscriberError::Provider(error.to_string()))?;
    let serde_json::Value::Object(mut fields) = encoded else {
        return Err(SubscriberError::Provider(
            "Alloy log filter did not serialize as an object".into(),
        ));
    };
    fields.retain(|key, _| key == "address" || key == "topics");
    Ok(serde_json::Value::Object(fields))
}

fn provider_error(error: impl fmt::Display) -> SubscriberError {
    SubscriberError::Provider(error.to_string())
}

/// Subscriber error.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SubscriberError {
    /// Invalid subscriber configuration.
    #[error("{0}")]
    InvalidConfig(&'static str),
    /// Requested subscriber behavior is not implemented.
    #[error("{0}")]
    Unsupported(&'static str),
    /// Provider or transport error.
    #[error("provider error: {0}")]
    Provider(String),
    /// A provider returned malformed, out-of-range, or non-canonical lazy
    /// backfill data.
    #[error("invalid canonical backfill: {0}")]
    InvalidBackfill(String),
    /// A configured subscriber memory/concurrency boundary was exceeded.
    #[error("subscriber resource limit exceeded: {0}")]
    ResourceExhausted(String),
}