Skip to main content

evm_fork_cache_hypersync/
source_engine.rs

1use std::pin::Pin;
2
3use async_trait::async_trait;
4use evm_fork_cache_event_protocol::{
5    MAX_MESSAGE_SIZE_BYTES,
6    v1::{ApplyDesiredState, Barrier, BlockRef, Cursor, Delivery, Reorg, delivery},
7};
8use futures::Stream;
9use hypersync_client::{
10    format::Hash,
11    net_types::{BlockField, Query, RollbackGuard},
12};
13use prost::Message;
14
15use crate::{
16    CanonicalError, CanonicalTracker, NormalizeError, QueryPlanError, ReorgDelta, SourcePage,
17    SourcePageError,
18    normalize::{block_ref, encode_source_checkpoint, normalize_page_at},
19    page_validation::validate_source_page,
20    query_plan::{MAX_BLOCKS_PER_QUERY, MAX_LOGS_PER_QUERY, compile_query_with_limits},
21};
22
23/// Maximum encoded delivery accepted from this adapter before the gRPC envelope is added.
24pub const MAX_DELIVERY_SIZE_BYTES: usize = MAX_MESSAGE_SIZE_BYTES - 64 * 1024;
25/// Hard local block-row ceiling, independent of HyperSync's soft query target.
26pub const MAX_BLOCKS_PER_RESPONSE: usize = MAX_BLOCKS_PER_QUERY * 2;
27/// Hard local log-row ceiling, independent of HyperSync's soft query target.
28pub const MAX_LOGS_PER_RESPONSE: usize = MAX_LOGS_PER_QUERY * 2;
29/// Hard local ceiling for provider-owned row and field bytes in one decoded response.
30pub const MAX_DYNAMIC_BYTES_PER_RESPONSE: usize = 16 * 1024 * 1024;
31
32/// Hard local admission policy applied immediately after a provider response is decoded.
33///
34/// HyperSync's `max_num_blocks` and `max_num_logs` query fields are batching
35/// targets, not response guarantees. These limits are deliberately separate:
36/// modest soft-target overshoot remains interoperable, while a buggy or
37/// compromised provider cannot make this adapter sort, clone, or normalize an
38/// unbounded decoded page.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40#[non_exhaustive]
41pub struct SourceResponseLimits {
42    max_blocks: usize,
43    max_logs: usize,
44    max_dynamic_bytes: usize,
45}
46
47impl SourceResponseLimits {
48    /// Create a nonzero hard response policy.
49    ///
50    /// # Errors
51    ///
52    /// Returns [`SourceError::InvalidResponseLimit`] when any limit is zero.
53    pub fn new(
54        max_blocks: usize,
55        max_logs: usize,
56        max_dynamic_bytes: usize,
57    ) -> Result<Self, SourceError> {
58        if max_blocks == 0 {
59            return Err(SourceError::InvalidResponseLimit { resource: "blocks" });
60        }
61        if max_logs == 0 {
62            return Err(SourceError::InvalidResponseLimit { resource: "logs" });
63        }
64        if max_dynamic_bytes == 0 {
65            return Err(SourceError::InvalidResponseLimit {
66                resource: "dynamic bytes",
67            });
68        }
69        Ok(Self {
70            max_blocks,
71            max_logs,
72            max_dynamic_bytes,
73        })
74    }
75
76    /// Maximum decoded block rows admitted from one provider response.
77    pub const fn max_blocks(&self) -> usize {
78        self.max_blocks
79    }
80
81    /// Maximum decoded log rows admitted from one provider response.
82    pub const fn max_logs(&self) -> usize {
83        self.max_logs
84    }
85
86    /// Maximum provider-owned row and field bytes admitted from one decoded response.
87    pub const fn max_dynamic_bytes(&self) -> usize {
88        self.max_dynamic_bytes
89    }
90}
91
92impl Default for SourceResponseLimits {
93    fn default() -> Self {
94        Self {
95            max_blocks: MAX_BLOCKS_PER_RESPONSE,
96            max_logs: MAX_LOGS_PER_RESPONSE,
97            max_dynamic_bytes: MAX_DYNAMIC_BYTES_PER_RESPONSE,
98        }
99    }
100}
101
102/// Provider-neutral stream of exclusive archive-height updates.
103pub type ChainHeightStream = Pin<Box<dyn Stream<Item = u64> + Send + 'static>>;
104
105/// Async boundary around HyperSync, mockable at the external service edge.
106#[async_trait]
107pub trait ChainDataSource: Send + Sync {
108    /// Return the current exclusive archive height.
109    ///
110    /// Blocks with numbers strictly below this height are available to query.
111    ///
112    /// # Errors
113    ///
114    /// Returns [`SourceError`] when the external provider is unavailable,
115    /// rejects the request, times out, or cannot supply a usable height.
116    async fn height(&self) -> Result<u64, SourceError>;
117
118    /// Execute one bounded query page.
119    ///
120    /// # Errors
121    ///
122    /// Returns [`SourceError`] when the external provider/transport rejects,
123    /// times out, or cannot complete the query.
124    async fn query(&self, query: Query) -> Result<SourcePage, SourceError>;
125
126    /// Subscribe to archive-height updates when the provider offers a push
127    /// channel. Returning `None` leaves the service on its polling fallback.
128    fn height_stream(&self) -> Option<ChainHeightStream> {
129        None
130    }
131}
132
133/// One-in-flight source engine with at-least-once replay semantics.
134pub struct SourceEngine<S> {
135    source: S,
136    desired_state: ApplyDesiredState,
137    committed_next_block: u64,
138    committed_sequence: u64,
139    activation_block: u64,
140    owner_backfill_activation_block: Option<u64>,
141    coverage_head: Option<BlockRef>,
142    canonical: CanonicalTracker,
143    previous_guard: Option<RollbackGuard>,
144    max_delivery_bytes: usize,
145    response_limits: SourceResponseLimits,
146    pending: Option<PendingDelivery>,
147    queued: Option<PendingDelivery>,
148}
149
150struct PendingDelivery {
151    delivery: Delivery,
152    rollback_guard: Option<RollbackGuard>,
153    advances_source: bool,
154}
155
156/// Durable state used to rebuild a source engine after process restart.
157#[derive(Clone, Debug)]
158#[non_exhaustive]
159pub struct SourceResume {
160    /// Exclusive provider block cursor.
161    pub next_block: u64,
162    /// Last committed delivery sequence.
163    pub sequence: u64,
164    /// First block routed to all live owners for this desired-state revision.
165    pub activation_block: u64,
166    /// Portable activation boundary preserved exactly for this revision.
167    pub owner_backfill_activation_block: Option<u64>,
168    /// Retained canonical suffix used for post-restart reorg resolution.
169    pub canonical_blocks: Vec<BlockRef>,
170    /// Provider-native rollback/checkpoint state.
171    pub provider_checkpoint: Option<RollbackGuard>,
172    /// Runtime-global canonical coverage, independent of the provider scan cursor.
173    pub coverage_head: Option<BlockRef>,
174}
175
176impl SourceResume {
177    /// Create a resume position without retained canonical or provider-native metadata.
178    pub fn new(next_block: u64, sequence: u64, activation_block: u64) -> Self {
179        Self {
180            next_block,
181            sequence,
182            activation_block,
183            owner_backfill_activation_block: Some(activation_block),
184            canonical_blocks: Vec::new(),
185            provider_checkpoint: None,
186            coverage_head: None,
187        }
188    }
189
190    /// Attach the retained normalized canonical suffix.
191    pub fn with_canonical_blocks(mut self, canonical_blocks: Vec<BlockRef>) -> Self {
192        self.canonical_blocks = canonical_blocks;
193        self
194    }
195
196    /// Attach the provider-native checkpoint that agrees with the normalized suffix.
197    pub fn with_provider_checkpoint(mut self, provider_checkpoint: Option<RollbackGuard>) -> Self {
198        self.provider_checkpoint = provider_checkpoint;
199        self
200    }
201
202    /// Attach the runtime-global canonical coverage restored from the durable cursor.
203    pub fn with_coverage_head(mut self, coverage_head: Option<BlockRef>) -> Self {
204        self.coverage_head = coverage_head;
205        self
206    }
207}
208
209impl<S> SourceEngine<S>
210where
211    S: ChainDataSource,
212{
213    /// Create an engine at an acknowledged block cursor.
214    pub fn new(
215        source: S,
216        desired_state: ApplyDesiredState,
217        committed_next_block: u64,
218        activation_block: u64,
219        reorg_depth: usize,
220    ) -> Self {
221        Self {
222            source,
223            desired_state,
224            committed_next_block,
225            committed_sequence: 0,
226            activation_block,
227            owner_backfill_activation_block: Some(activation_block),
228            coverage_head: None,
229            canonical: CanonicalTracker::new(reorg_depth),
230            previous_guard: None,
231            max_delivery_bytes: MAX_DELIVERY_SIZE_BYTES,
232            response_limits: SourceResponseLimits::default(),
233            pending: None,
234            queued: None,
235        }
236    }
237
238    /// Restore an engine from a mutually consistent cursor, canonical suffix,
239    /// and provider checkpoint.
240    ///
241    /// # Errors
242    ///
243    /// Returns [`SourceEngineError`] when retained canonical history,
244    /// provider checkpoint, scan cursor, activation metadata, or coverage head
245    /// are malformed or mutually inconsistent.
246    pub fn restore(
247        source: S,
248        desired_state: ApplyDesiredState,
249        resume: SourceResume,
250        reorg_depth: usize,
251    ) -> Result<Self, SourceEngineError> {
252        let mut canonical = CanonicalTracker::new(reorg_depth);
253        if !resume.canonical_blocks.is_empty() {
254            canonical.apply_blocks(resume.canonical_blocks)?;
255        }
256        let previous_guard =
257            validate_resume_state(&canonical, resume.next_block, resume.provider_checkpoint)?;
258        validate_coverage_state(&canonical, resume.next_block, resume.coverage_head.as_ref())?;
259        Ok(Self {
260            source,
261            desired_state,
262            committed_next_block: resume.next_block,
263            committed_sequence: resume.sequence,
264            activation_block: resume.activation_block,
265            owner_backfill_activation_block: resume.owner_backfill_activation_block,
266            coverage_head: resume.coverage_head,
267            canonical,
268            previous_guard,
269            max_delivery_bytes: MAX_DELIVERY_SIZE_BYTES,
270            response_limits: SourceResponseLimits::default(),
271            pending: None,
272            queued: None,
273        })
274    }
275
276    /// Override the encoded delivery budget, primarily for stricter deployments and tests.
277    ///
278    /// # Errors
279    ///
280    /// Returns [`SourceEngineError::InvalidDeliverySizeLimit`] when the limit
281    /// is zero or exceeds [`MAX_DELIVERY_SIZE_BYTES`].
282    pub fn with_max_delivery_bytes(
283        mut self,
284        max_delivery_bytes: usize,
285    ) -> Result<Self, SourceEngineError> {
286        if max_delivery_bytes == 0 || max_delivery_bytes > MAX_DELIVERY_SIZE_BYTES {
287            return Err(SourceEngineError::InvalidDeliverySizeLimit {
288                requested: max_delivery_bytes,
289                maximum: MAX_DELIVERY_SIZE_BYTES,
290            });
291        }
292        self.max_delivery_bytes = max_delivery_bytes;
293        Ok(self)
294    }
295
296    /// Override the hard local decoded-response admission policy.
297    pub fn with_response_limits(mut self, response_limits: SourceResponseLimits) -> Self {
298        self.response_limits = response_limits;
299        self
300    }
301
302    /// Fetch the next page up to an exclusive target, replaying an unacknowledged
303    /// page without another provider request.
304    ///
305    /// # Errors
306    ///
307    /// Returns [`SourceEngineError`] for query/source failure, invalid or
308    /// oversized provider data, unresolvable continuity/reorg state, sequence
309    /// exhaustion, or an owner-only fork protocol v1 cannot represent.
310    pub async fn next_batch(
311        &mut self,
312        to_block_excl: u64,
313    ) -> Result<Option<Delivery>, SourceEngineError> {
314        if let Some(pending) = &self.pending {
315            return Ok(Some(pending.delivery.clone()));
316        }
317        if self.committed_next_block >= to_block_excl {
318            return Ok(None);
319        }
320        let sequence = self
321            .committed_sequence
322            .checked_add(1)
323            .ok_or(SourceEngineError::SequenceExhausted)?;
324
325        let mut query_limits = QueryLimits::for_range(self.committed_next_block, to_block_excl);
326        let mut initial_anchor = None;
327        let (mut delivery, rollback_guard, canonical, reorg) = loop {
328            let page = self
329                .query_page(self.committed_next_block, to_block_excl, query_limits)
330                .await?;
331            if initial_anchor.is_none() {
332                initial_anchor = self.query_canonical_anchor(&page).await?;
333            }
334            let prepared = if self.rollback_detected(&page) {
335                self.recover_rollback(to_block_excl, sequence, query_limits)
336                    .await?
337            } else {
338                self.prepare_batch(page, sequence, initial_anchor.as_ref())?
339            };
340            let encoded_len = prepared.0.encoded_len();
341            if encoded_len <= self.max_delivery_bytes {
342                break prepared;
343            }
344            if !query_limits.shrink() {
345                return Err(SourceEngineError::DeliveryTooLarge {
346                    encoded_len,
347                    limit: self.max_delivery_bytes,
348                });
349            }
350        };
351        if let Some(reorg) = reorg {
352            // Every block on the previously delivered branch was owner-only.
353            // The v1 protocol intentionally has no owner-scoped reorg control,
354            // so emitting its global Reorg here would rewind unrelated runtime
355            // coverage. Do not silently send replacement records either: an
356            // acknowledged owner may already have applied the displaced branch.
357            // Fail closed until a fresh desired-state revision restarts that
358            // owner's catch-up from an authoritative position.
359            if reorg.old_tip.number < self.activation_block
360                && !global_backfill_contains(&self.desired_state, reorg.old_tip.number)
361            {
362                return Err(SourceEngineError::OwnerCatchupReorg {
363                    activation_block: self.activation_block,
364                    common_ancestor: reorg.common_ancestor.number,
365                    old_tip: reorg.old_tip.number,
366                    new_tip: reorg.new_tip.number,
367                });
368            }
369            let replacement_sequence = sequence
370                .checked_add(1)
371                .ok_or(SourceEngineError::SequenceExhausted)?;
372            set_delivery_sequence(&mut delivery, replacement_sequence)?;
373            let control = self.reorg_delivery(sequence, reorg)?;
374            let encoded_len = control.encoded_len();
375            if encoded_len > self.max_delivery_bytes {
376                return Err(SourceEngineError::DeliveryTooLarge {
377                    encoded_len,
378                    limit: self.max_delivery_bytes,
379                });
380            }
381            self.canonical = canonical;
382            self.queued = Some(PendingDelivery {
383                delivery,
384                rollback_guard,
385                advances_source: true,
386            });
387            self.pending = Some(PendingDelivery {
388                delivery: control.clone(),
389                rollback_guard: self.previous_guard.clone(),
390                advances_source: false,
391            });
392            Ok(Some(control))
393        } else {
394            self.canonical = canonical;
395            self.pending = Some(PendingDelivery {
396                delivery: delivery.clone(),
397                rollback_guard,
398                advances_source: true,
399            });
400            Ok(Some(delivery))
401        }
402    }
403
404    /// Commit the only in-flight delivery token and advance the durable cursor.
405    ///
406    /// # Errors
407    ///
408    /// Returns [`SourceEngineError::NoPendingDelivery`] when nothing is in
409    /// flight, [`SourceEngineError::DeliveryTokenMismatch`] for the wrong
410    /// token, or [`SourceEngineError::MissingCursor`] for an invalid pending
411    /// delivery.
412    pub fn acknowledge(&mut self, delivery_token: &[u8]) -> Result<(), SourceEngineError> {
413        let pending = self
414            .pending
415            .as_ref()
416            .ok_or(SourceEngineError::NoPendingDelivery)?;
417        if pending.delivery.delivery_token != delivery_token {
418            return Err(SourceEngineError::DeliveryTokenMismatch);
419        }
420        let cursor = pending
421            .delivery
422            .cursor
423            .as_ref()
424            .ok_or(SourceEngineError::MissingCursor)?;
425        let committed_next_block = cursor.next_block;
426        let committed_sequence = pending.delivery.sequence;
427        let advances_source = pending.advances_source;
428        let rollback_guard = pending.rollback_guard.clone();
429        let coverage_head = cursor.canonical_head.clone();
430        if advances_source {
431            self.committed_next_block = committed_next_block;
432            self.previous_guard = rollback_guard;
433        }
434        self.committed_sequence = committed_sequence;
435        self.coverage_head = coverage_head;
436        self.pending = self.queued.take();
437        Ok(())
438    }
439
440    /// Exclusive block cursor durably acknowledged by the consumer.
441    pub fn committed_next_block(&self) -> u64 {
442        self.committed_next_block
443    }
444
445    /// Cursor persisted on the desired-state activation barrier before the
446    /// first provider page is requested.
447    ///
448    /// # Errors
449    ///
450    /// Returns [`SourceEngineError`] when retained canonical/provider
451    /// checkpoint metadata cannot be encoded safely.
452    pub fn activation_cursor(&self) -> Result<Cursor, SourceEngineError> {
453        Ok(Cursor {
454            chain_id: self.desired_state.chain_id,
455            query_revision: self.desired_state.new_revision,
456            next_block: self.committed_next_block,
457            canonical_head: self.coverage_head.clone(),
458            batch_sequence: self.committed_sequence,
459            provider_checkpoint: encode_source_checkpoint(
460                self.previous_guard.as_ref(),
461                self.activation_block,
462                self.canonical.blocks(),
463            )?,
464            owner_backfill_activation_block: self.owner_backfill_activation_block,
465        })
466    }
467
468    /// Last batch sequence durably acknowledged by the consumer.
469    pub fn committed_sequence(&self) -> u64 {
470        self.committed_sequence
471    }
472
473    /// Advance sequence across a service-generated control that does not touch
474    /// this source's provider cursor.
475    ///
476    /// # Errors
477    ///
478    /// Returns [`SourceEngineError::PendingDelivery`] while a source delivery
479    /// is in flight, or [`SourceEngineError::SequenceRegression`] if `sequence`
480    /// moves behind committed authority.
481    pub fn acknowledge_external_control(&mut self, sequence: u64) -> Result<(), SourceEngineError> {
482        if self.pending.is_some() {
483            return Err(SourceEngineError::PendingDelivery);
484        }
485        if sequence < self.committed_sequence {
486            return Err(SourceEngineError::SequenceRegression {
487                committed: self.committed_sequence,
488                received: sequence,
489            });
490        }
491        self.committed_sequence = sequence;
492        Ok(())
493    }
494
495    /// Synchronize an engine rebuilt from an older acknowledged cursor after a
496    /// separately persisted outbox delivery is committed.
497    ///
498    /// # Errors
499    ///
500    /// Returns [`SourceEngineError`] when a delivery is pending, sequence
501    /// authority regresses, or the replacement cursor/checkpoint/history/
502    /// coverage state is malformed or inconsistent. Validation completes
503    /// before engine state is replaced.
504    pub fn synchronize_committed_cursor(
505        &mut self,
506        resume: SourceResume,
507    ) -> Result<(), SourceEngineError> {
508        if self.pending.is_some() {
509            return Err(SourceEngineError::PendingDelivery);
510        }
511        if resume.sequence < self.committed_sequence {
512            return Err(SourceEngineError::SequenceRegression {
513                committed: self.committed_sequence,
514                received: resume.sequence,
515            });
516        }
517        let mut canonical = self.canonical.clone();
518        canonical.restore_blocks(resume.canonical_blocks)?;
519        let previous_guard =
520            validate_resume_state(&canonical, resume.next_block, resume.provider_checkpoint)?;
521        validate_coverage_state(&canonical, resume.next_block, resume.coverage_head.as_ref())?;
522        self.canonical = canonical;
523        self.committed_next_block = resume.next_block;
524        self.committed_sequence = resume.sequence;
525        self.activation_block = resume.activation_block;
526        self.previous_guard = previous_guard;
527        self.coverage_head = resume.coverage_head;
528        self.owner_backfill_activation_block = resume.owner_backfill_activation_block;
529        Ok(())
530    }
531
532    /// First block routed to all live owners for the active revision.
533    pub fn activation_block(&self) -> u64 {
534        self.activation_block
535    }
536
537    /// Access the source, primarily for lifecycle and height-stream drivers.
538    pub fn source(&self) -> &S {
539        &self.source
540    }
541
542    async fn query_page(
543        &self,
544        from_block: u64,
545        to_block_excl: u64,
546        limits: QueryLimits,
547    ) -> Result<SourcePage, SourceEngineError> {
548        let query = compile_query_with_limits(
549            &self.desired_state,
550            from_block,
551            Some(to_block_excl),
552            limits.max_blocks,
553            limits.max_logs,
554        )?;
555        let page = self.source.query(query).await?;
556        validate_response_counts(&page, self.response_limits)?;
557        if page.next_block <= from_block {
558            return Err(SourceEngineError::NoProgress {
559                from_block,
560                next_block: page.next_block,
561            });
562        }
563        validate_source_page(&page, from_block, to_block_excl)?;
564        Ok(page)
565    }
566
567    async fn query_canonical_anchor(
568        &self,
569        page: &SourcePage,
570    ) -> Result<Option<BlockRef>, SourceEngineError> {
571        if !self.canonical.is_empty() {
572            return Ok(None);
573        }
574        let Some(guard) = page.rollback_guard.as_ref() else {
575            return Ok(None);
576        };
577        let Some(anchor_number) = guard.first_block_number.checked_sub(1) else {
578            return Ok(None);
579        };
580        let anchor_end = anchor_number
581            .checked_add(1)
582            .ok_or(SourceEngineError::BlockNumberOverflow)?;
583        let mut query = Query::new()
584            .from_block(anchor_number)
585            .to_block_excl(anchor_end)
586            .include_all_blocks()
587            .select_block_fields([
588                BlockField::Number,
589                BlockField::Hash,
590                BlockField::ParentHash,
591                BlockField::Timestamp,
592            ]);
593        query.max_num_blocks = Some(1);
594        query.max_num_logs = Some(1);
595        let anchor_page = self.source.query(query).await?;
596        validate_response_counts(&anchor_page, self.response_limits)?;
597        if anchor_page.next_block <= anchor_number {
598            return Err(SourceEngineError::NoProgress {
599                from_block: anchor_number,
600                next_block: anchor_page.next_block,
601            });
602        }
603        validate_source_page(&anchor_page, anchor_number, anchor_end)?;
604        let anchor = block_ref(
605            anchor_page
606                .blocks
607                .first()
608                .expect("validated one-block anchor page"),
609        )?;
610        if anchor.hash.as_slice() != guard.first_parent_hash.as_ref() {
611            return Err(CanonicalError::UnknownParent {
612                number: guard.first_block_number,
613                parent_hash: guard.first_parent_hash.as_ref().to_vec(),
614            }
615            .into());
616        }
617        Ok(Some(anchor))
618    }
619
620    fn rollback_detected(&self, page: &SourcePage) -> bool {
621        match (&self.previous_guard, &page.rollback_guard) {
622            (Some(previous), Some(current)) => {
623                current.first_block_number <= previous.block_number.saturating_add(1)
624                    && current.first_parent_hash != previous.hash
625            }
626            _ => false,
627        }
628    }
629
630    async fn recover_rollback(
631        &self,
632        to_block_excl: u64,
633        sequence: u64,
634        limits: QueryLimits,
635    ) -> Result<PreparedPage, SourceEngineError> {
636        let previous = self
637            .previous_guard
638            .as_ref()
639            .ok_or(SourceEngineError::MissingRollbackGuard)?;
640        let oldest = self
641            .canonical
642            .blocks()
643            .next()
644            .map(|block| block.number)
645            .ok_or(CanonicalError::HistoryExhausted {
646                required_block: previous.block_number,
647            })?;
648        let newest = self
649            .canonical
650            .tip()
651            .map(|block| block.number.min(previous.block_number))
652            .ok_or(CanonicalError::HistoryExhausted {
653                required_block: previous.block_number,
654            })?;
655
656        // A canonical fork is a shared prefix followed by a replacement
657        // suffix. Probe that monotonic boundary instead of issuing one query
658        // per retained height. Exact BlockRef equality is required: a hash may
659        // not silently acquire a different parent or timestamp.
660        let mut low = oldest;
661        let mut high = newest;
662        let mut common_ancestor = None;
663        while low <= high {
664            let candidate = low + (high - low) / 2;
665            let observed = self.query_canonical_block(candidate).await?;
666            let expected = self
667                .canonical
668                .block(candidate)
669                .expect("binary probe stays inside retained canonical history");
670            if observed.hash == expected.hash {
671                if observed != *expected {
672                    return Err(
673                        CanonicalError::ConflictingBlockMetadata { number: candidate }.into(),
674                    );
675                }
676                common_ancestor = Some(candidate);
677                let Some(next) = candidate.checked_add(1) else {
678                    break;
679                };
680                low = next;
681            } else if candidate == 0 {
682                break;
683            } else {
684                high = candidate - 1;
685            }
686        }
687        let common_ancestor = common_ancestor.ok_or(CanonicalError::HistoryExhausted {
688            required_block: oldest.saturating_sub(1),
689        })?;
690        let replacement_start = common_ancestor
691            .checked_add(1)
692            .ok_or(SourceEngineError::BlockNumberOverflow)?;
693        let page = self
694            .query_page(replacement_start, to_block_excl, limits)
695            .await?;
696        self.prepare_batch(page, sequence, None)
697    }
698
699    async fn query_canonical_block(&self, number: u64) -> Result<BlockRef, SourceEngineError> {
700        let end = number
701            .checked_add(1)
702            .ok_or(SourceEngineError::BlockNumberOverflow)?;
703        let mut query = Query::new()
704            .from_block(number)
705            .to_block_excl(end)
706            .include_all_blocks()
707            .select_block_fields([
708                BlockField::Number,
709                BlockField::Hash,
710                BlockField::ParentHash,
711                BlockField::Timestamp,
712            ]);
713        query.max_num_blocks = Some(1);
714        query.max_num_logs = Some(1);
715        let page = self.source.query(query).await?;
716        validate_response_counts(&page, self.response_limits)?;
717        if page.next_block <= number {
718            return Err(SourceEngineError::NoProgress {
719                from_block: number,
720                next_block: page.next_block,
721            });
722        }
723        validate_source_page(&page, number, end)?;
724        block_ref(page.blocks.first().expect("validated single-block page")).map_err(Into::into)
725    }
726
727    fn prepare_batch(
728        &self,
729        page: SourcePage,
730        sequence: u64,
731        initial_anchor: Option<&BlockRef>,
732    ) -> Result<PreparedPage, SourceEngineError> {
733        let rollback_guard = page.rollback_guard.clone();
734        let page_blocks = page
735            .blocks
736            .iter()
737            .map(block_ref)
738            .collect::<Result<Vec<_>, _>>()?;
739        // Retained source history normally proves continuity itself. A
740        // coverage-only restore (or owner rescan below that coverage) has no
741        // such tracker edge, so compare the page directly to the durable
742        // coverage identity. Do not apply this shortcut during rollback
743        // recovery: its replacement page is expected to conflict with the
744        // displaced tracked tip and is validated by `CanonicalTracker`.
745        let crosses_untracked_coverage_boundary =
746            self.coverage_head.as_ref().is_some_and(|coverage| {
747                self.canonical.is_empty() || self.committed_next_block <= coverage.number
748            });
749        if initial_anchor.is_some() || crosses_untracked_coverage_boundary {
750            validate_coverage_boundary(self.coverage_head.as_ref(), &page_blocks, initial_anchor)?;
751        }
752        let mut delivery =
753            normalize_page_at(&self.desired_state, sequence, page, self.activation_block)?;
754        let mut canonical = self.canonical.clone();
755        if canonical.is_empty()
756            && let Some(anchor) = initial_anchor
757        {
758            canonical.apply_blocks([anchor.clone()])?;
759        }
760        let reorg = canonical.apply_blocks(page_blocks)?;
761        delivery
762            .cursor
763            .as_mut()
764            .ok_or(SourceEngineError::MissingCursor)?
765            .provider_checkpoint = encode_source_checkpoint(
766            rollback_guard.as_ref(),
767            self.activation_block,
768            canonical.blocks(),
769        )?;
770        let cursor = delivery
771            .cursor
772            .as_mut()
773            .expect("delivery cursor was validated above");
774        cursor.owner_backfill_activation_block = self.owner_backfill_activation_block;
775        if cursor.canonical_head.is_none() {
776            cursor.canonical_head = self.coverage_head.clone();
777        }
778        if matches!(
779            delivery.payload.as_ref(),
780            Some(delivery::Payload::Data(data)) if data.records.is_empty()
781        ) {
782            let progress_block = delivery
783                .cursor
784                .as_ref()
785                .and_then(|cursor| cursor.canonical_head.clone())
786                .filter(|head| self.coverage_head.as_ref() != Some(head));
787            delivery.payload = Some(delivery::Payload::Barrier(Barrier {
788                id: format!(
789                    "source-progress:{}:{}",
790                    self.desired_state.new_revision,
791                    delivery
792                        .cursor
793                        .as_ref()
794                        .expect("validated cursor")
795                        .next_block
796                )
797                .into_bytes(),
798                block: progress_block.clone(),
799            }));
800            delivery.checkpoint_neutral = progress_block.is_none();
801        }
802        Ok((delivery, rollback_guard, canonical, reorg))
803    }
804
805    fn reorg_delivery(
806        &self,
807        sequence: u64,
808        reorg: ReorgDelta,
809    ) -> Result<Delivery, SourceEngineError> {
810        let next_block = reorg
811            .common_ancestor
812            .number
813            .checked_add(1)
814            .ok_or(SourceEngineError::BlockNumberOverflow)?;
815        let rollback_guard = rollback_guard_at(&reorg.common_ancestor)?;
816        let canonical_prefix: Vec<_> = self
817            .canonical
818            .blocks()
819            .take_while(|block| block.number <= reorg.common_ancestor.number)
820            .collect();
821        Ok(Delivery {
822            session_id: self.desired_state.session_id.clone(),
823            sequence,
824            query_revision: self.desired_state.new_revision,
825            delivery_token: sequence.to_be_bytes().to_vec(),
826            cursor: Some(Cursor {
827                chain_id: self.desired_state.chain_id,
828                query_revision: self.desired_state.new_revision,
829                next_block,
830                canonical_head: Some(reorg.common_ancestor.clone()),
831                batch_sequence: sequence,
832                provider_checkpoint: encode_source_checkpoint(
833                    Some(&rollback_guard),
834                    self.activation_block,
835                    canonical_prefix.into_iter(),
836                )?,
837                owner_backfill_activation_block: self.owner_backfill_activation_block,
838            }),
839            payload: Some(delivery::Payload::Reorg(Reorg {
840                common_ancestor: Some(reorg.common_ancestor),
841                old_tip: Some(reorg.old_tip),
842                new_tip: Some(reorg.new_tip),
843            })),
844            checkpoint_neutral: false,
845        })
846    }
847}
848
849fn global_backfill_contains(desired_state: &ApplyDesiredState, block_number: u64) -> bool {
850    desired_state.owners.iter().any(|owner| {
851        owner.canonical
852            && owner.backfill.as_ref().is_some_and(|backfill| {
853                block_number >= backfill.from_block
854                    && backfill.to_block_excl.is_none_or(|end| block_number < end)
855            })
856    })
857}
858
859fn validate_coverage_state(
860    canonical: &CanonicalTracker,
861    next_block: u64,
862    coverage_head: Option<&BlockRef>,
863) -> Result<(), SourceEngineError> {
864    let Some(coverage_head) = coverage_head else {
865        return Ok(());
866    };
867    let mut validator = CanonicalTracker::new(1);
868    validator.apply_blocks([coverage_head.clone()])?;
869    let coverage_successor = coverage_head
870        .number
871        .checked_add(1)
872        .ok_or(SourceEngineError::BlockNumberOverflow)?;
873    if next_block > coverage_successor {
874        return Err(SourceEngineError::CoverageCursorMismatch {
875            coverage_successor,
876            received: next_block,
877        });
878    }
879    if let Some(scanned) = canonical.block(coverage_head.number)
880        && scanned != coverage_head
881    {
882        return Err(SourceEngineError::CoverageBoundaryConflict {
883            number: coverage_head.number,
884        });
885    }
886    Ok(())
887}
888
889fn validate_coverage_boundary(
890    coverage_head: Option<&BlockRef>,
891    page_blocks: &[BlockRef],
892    initial_anchor: Option<&BlockRef>,
893) -> Result<(), SourceEngineError> {
894    let Some(coverage_head) = coverage_head else {
895        return Ok(());
896    };
897    if let Some(observed) = page_blocks
898        .iter()
899        .find(|block| block.number == coverage_head.number)
900        .or_else(|| initial_anchor.filter(|block| block.number == coverage_head.number))
901        && observed != coverage_head
902    {
903        return Err(SourceEngineError::CoverageBoundaryConflict {
904            number: coverage_head.number,
905        });
906    }
907    if let Some(first) = page_blocks.first()
908        && first.number == coverage_head.number.saturating_add(1)
909        && first.parent_hash != coverage_head.hash
910    {
911        return Err(SourceEngineError::CoverageBoundaryConflict {
912            number: coverage_head.number,
913        });
914    }
915    Ok(())
916}
917
918pub(crate) fn validate_response_counts(
919    page: &SourcePage,
920    limits: SourceResponseLimits,
921) -> Result<(), SourceEngineError> {
922    if page.blocks.len() > limits.max_blocks {
923        return Err(SourceEngineError::ResponseLimitExceeded {
924            resource: "blocks",
925            observed: page.blocks.len(),
926            limit: limits.max_blocks,
927        });
928    }
929    if page.logs.len() > limits.max_logs {
930        return Err(SourceEngineError::ResponseLimitExceeded {
931            resource: "logs",
932            observed: page.logs.len(),
933            limit: limits.max_logs,
934        });
935    }
936    validate_response_dynamic_bytes(page, limits.max_dynamic_bytes)?;
937    Ok(())
938}
939
940fn validate_response_dynamic_bytes(
941    page: &SourcePage,
942    limit: usize,
943) -> Result<(), SourceEngineError> {
944    // Row storage includes every inline field, notably Log's fixed-capacity
945    // ArrayVec<Option<LogArgument>, 4>. Only heap-owned fields are added below;
946    // charging `log.topics.as_slice()` again would double-count inline bytes.
947    let mut observed = std::mem::size_of::<hypersync_client::simple_types::Block>()
948        .saturating_mul(page.blocks.capacity())
949        .saturating_add(
950            std::mem::size_of::<hypersync_client::simple_types::Log>()
951                .saturating_mul(page.logs.capacity()),
952        );
953    check_dynamic_bytes(observed, limit)?;
954
955    macro_rules! add_bytes {
956        ($value:expr) => {
957            if let Some(value) = $value.as_ref() {
958                observed = observed.saturating_add(value.as_ref().len());
959                check_dynamic_bytes(observed, limit)?;
960            }
961        };
962    }
963
964    for block in &page.blocks {
965        add_bytes!(block.hash);
966        add_bytes!(block.parent_hash);
967        add_bytes!(block.nonce);
968        add_bytes!(block.sha3_uncles);
969        add_bytes!(block.logs_bloom);
970        add_bytes!(block.transactions_root);
971        add_bytes!(block.state_root);
972        add_bytes!(block.receipts_root);
973        add_bytes!(block.miner);
974        add_bytes!(block.difficulty);
975        add_bytes!(block.total_difficulty);
976        add_bytes!(block.extra_data);
977        add_bytes!(block.size);
978        add_bytes!(block.gas_limit);
979        add_bytes!(block.gas_used);
980        add_bytes!(block.timestamp);
981        add_bytes!(block.base_fee_per_gas);
982        add_bytes!(block.blob_gas_used);
983        add_bytes!(block.excess_blob_gas);
984        add_bytes!(block.parent_beacon_block_root);
985        add_bytes!(block.withdrawals_root);
986        add_bytes!(block.send_count);
987        add_bytes!(block.send_root);
988        add_bytes!(block.mix_hash);
989        if let Some(uncles) = &block.uncles {
990            observed = observed
991                .saturating_add(std::mem::size_of::<Hash>().saturating_mul(uncles.capacity()));
992            check_dynamic_bytes(observed, limit)?;
993            for uncle in uncles {
994                observed = observed.saturating_add(uncle.as_ref().len());
995                check_dynamic_bytes(observed, limit)?;
996            }
997        }
998        if let Some(withdrawals) = &block.withdrawals {
999            observed = observed.saturating_add(
1000                std::mem::size_of::<hypersync_client::format::Withdrawal>()
1001                    .saturating_mul(withdrawals.capacity()),
1002            );
1003            check_dynamic_bytes(observed, limit)?;
1004            for withdrawal in withdrawals {
1005                add_bytes!(withdrawal.index);
1006                add_bytes!(withdrawal.validator_index);
1007                add_bytes!(withdrawal.address);
1008                add_bytes!(withdrawal.amount);
1009            }
1010        }
1011    }
1012    for log in &page.logs {
1013        add_bytes!(log.transaction_hash);
1014        add_bytes!(log.block_hash);
1015        add_bytes!(log.address);
1016        add_bytes!(log.data);
1017        for topic in &log.topics {
1018            add_bytes!(topic);
1019        }
1020    }
1021    if let Some(guard) = &page.rollback_guard {
1022        observed = observed
1023            .saturating_add(guard.hash.as_ref().len())
1024            .saturating_add(guard.first_parent_hash.as_ref().len());
1025        check_dynamic_bytes(observed, limit)?;
1026    }
1027    Ok(())
1028}
1029
1030fn check_dynamic_bytes(observed: usize, limit: usize) -> Result<(), SourceEngineError> {
1031    if observed > limit {
1032        return Err(SourceEngineError::ResponseLimitExceeded {
1033            resource: "dynamic bytes",
1034            observed,
1035            limit,
1036        });
1037    }
1038    Ok(())
1039}
1040
1041fn rollback_guard_at(block: &BlockRef) -> Result<RollbackGuard, SourceEngineError> {
1042    let hash: [u8; 32] =
1043        block
1044            .hash
1045            .as_slice()
1046            .try_into()
1047            .map_err(|_| CanonicalError::InvalidHashWidth {
1048                field: "hash",
1049                width: block.hash.len(),
1050            })?;
1051    let parent_hash: [u8; 32] =
1052        block
1053            .parent_hash
1054            .as_slice()
1055            .try_into()
1056            .map_err(|_| CanonicalError::InvalidHashWidth {
1057                field: "parent_hash",
1058                width: block.parent_hash.len(),
1059            })?;
1060    Ok(RollbackGuard {
1061        block_number: block.number,
1062        timestamp: i64::try_from(block.timestamp)
1063            .map_err(|_| SourceEngineError::BlockTimestampOverflow(block.timestamp))?,
1064        hash: Hash::from(hash),
1065        first_block_number: block.number,
1066        first_parent_hash: Hash::from(parent_hash),
1067    })
1068}
1069
1070fn validate_resume_state(
1071    canonical: &CanonicalTracker,
1072    next_block: u64,
1073    provider_checkpoint: Option<RollbackGuard>,
1074) -> Result<Option<RollbackGuard>, SourceEngineError> {
1075    if provider_checkpoint
1076        .as_ref()
1077        .is_some_and(|guard| guard.first_block_number > guard.block_number)
1078    {
1079        return Err(SourceEngineError::ResumeGuardMismatch("first_block_number"));
1080    }
1081    let Some(tip) = canonical.tip() else {
1082        if let Some(guard) = provider_checkpoint {
1083            if guard.timestamp < 0 {
1084                return Err(SourceEngineError::ResumeGuardMismatch("timestamp"));
1085            }
1086            let expected = guard
1087                .block_number
1088                .checked_add(1)
1089                .ok_or(SourceEngineError::BlockNumberOverflow)?;
1090            if next_block != expected {
1091                return Err(SourceEngineError::ResumeCursorMismatch {
1092                    expected,
1093                    received: next_block,
1094                });
1095            }
1096            return Ok(Some(guard));
1097        }
1098        return Ok(None);
1099    };
1100
1101    let expected = tip
1102        .number
1103        .checked_add(1)
1104        .ok_or(SourceEngineError::BlockNumberOverflow)?;
1105    if next_block != expected {
1106        return Err(SourceEngineError::ResumeCursorMismatch {
1107            expected,
1108            received: next_block,
1109        });
1110    }
1111    let Some(guard) = provider_checkpoint else {
1112        return rollback_guard_at(tip).map(Some);
1113    };
1114    if guard.block_number != tip.number {
1115        return Err(SourceEngineError::ResumeGuardMismatch("block_number"));
1116    }
1117    if guard.hash.as_ref() != tip.hash {
1118        return Err(SourceEngineError::ResumeGuardMismatch("hash"));
1119    }
1120    let timestamp = i64::try_from(tip.timestamp)
1121        .map_err(|_| SourceEngineError::BlockTimestampOverflow(tip.timestamp))?;
1122    if guard.timestamp != timestamp {
1123        return Err(SourceEngineError::ResumeGuardMismatch("timestamp"));
1124    }
1125    Ok(Some(guard))
1126}
1127
1128type PreparedPage = (
1129    Delivery,
1130    Option<RollbackGuard>,
1131    CanonicalTracker,
1132    Option<ReorgDelta>,
1133);
1134
1135#[derive(Clone, Copy)]
1136struct QueryLimits {
1137    max_blocks: usize,
1138    max_logs: usize,
1139}
1140
1141impl QueryLimits {
1142    fn for_range(from_block: u64, to_block_excl: u64) -> Self {
1143        let span = to_block_excl.saturating_sub(from_block);
1144        let max_blocks = usize::try_from(span)
1145            .unwrap_or(MAX_BLOCKS_PER_QUERY)
1146            .clamp(1, MAX_BLOCKS_PER_QUERY);
1147        Self {
1148            max_blocks,
1149            max_logs: MAX_LOGS_PER_QUERY,
1150        }
1151    }
1152
1153    fn shrink(&mut self) -> bool {
1154        if self.max_blocks == 1 && self.max_logs == 1 {
1155            return false;
1156        }
1157        self.max_blocks = self.max_blocks.div_ceil(2).max(1);
1158        self.max_logs = self.max_logs.div_ceil(2).max(1);
1159        true
1160    }
1161}
1162
1163fn set_delivery_sequence(delivery: &mut Delivery, sequence: u64) -> Result<(), SourceEngineError> {
1164    delivery.sequence = sequence;
1165    delivery.delivery_token = sequence.to_be_bytes().to_vec();
1166    delivery
1167        .cursor
1168        .as_mut()
1169        .ok_or(SourceEngineError::MissingCursor)?
1170        .batch_sequence = sequence;
1171    Ok(())
1172}
1173
1174/// External source request failure.
1175#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
1176#[non_exhaustive]
1177pub enum SourceError {
1178    /// HyperSync or its transport rejected the request.
1179    ///
1180    /// This internal diagnostic may retain provider-supplied sensitive detail.
1181    /// Service adapters must map it to a static public error before crossing a
1182    /// remote trust boundary.
1183    #[error("chain data source request failed: {0}")]
1184    Request(String),
1185    /// The provider did not return a usable archive height for an established chain.
1186    #[error("chain data source archive height is unavailable")]
1187    UnavailableHeight,
1188    /// A source operation exceeded the configured end-to-end request deadline.
1189    #[error("chain data source request timed out after {millis}ms")]
1190    RequestTimeout {
1191        /// Configured deadline in milliseconds.
1192        millis: u128,
1193    },
1194    /// A zero request deadline would make every source operation fail immediately.
1195    #[error("chain data source request timeout must be greater than zero")]
1196    InvalidRequestTimeout,
1197    /// A zero resident-session limit would reject every source session.
1198    #[error("managed source resident-session limit must be greater than zero")]
1199    InvalidSessionLimit,
1200    /// A zero reorg history cannot certify or resolve even a one-block fork.
1201    #[error("managed source reorg depth must be greater than zero")]
1202    InvalidReorgDepth,
1203    /// A provider delivery budget must fit inside the protocol-safe envelope.
1204    #[error("source delivery size limit {requested} must be within 1..={maximum} bytes")]
1205    InvalidDeliverySizeLimit {
1206        /// Requested source delivery budget.
1207        requested: usize,
1208        /// Largest protocol-safe source delivery budget.
1209        maximum: usize,
1210    },
1211    /// A hard local provider-response limit must be nonzero.
1212    #[error("source response limit for {resource} must be greater than zero")]
1213    InvalidResponseLimit {
1214        /// Resource whose limit was invalid.
1215        resource: &'static str,
1216    },
1217}
1218
1219impl SourceError {
1220    /// Retain an external provider or transport failure for trusted local diagnostics.
1221    ///
1222    /// This constructor does not sanitize its argument. `ManagedEventProvider`
1223    /// deliberately converts the error to a static unavailable response before
1224    /// the event service exposes it over gRPC.
1225    pub fn request(message: impl Into<String>) -> Self {
1226        Self::Request(message.into())
1227    }
1228
1229    /// Report that the provider has no usable nonzero archive height yet.
1230    pub const fn unavailable_height() -> Self {
1231        Self::UnavailableHeight
1232    }
1233
1234    /// Report expiration of one configured end-to-end source deadline.
1235    pub fn request_timeout(timeout: std::time::Duration) -> Self {
1236        Self::RequestTimeout {
1237            millis: timeout.as_millis(),
1238        }
1239    }
1240}
1241
1242/// Source engine could not produce or commit an ordered delivery.
1243#[derive(Debug, thiserror::Error)]
1244#[non_exhaustive]
1245pub enum SourceEngineError {
1246    /// Portable interests could not compile.
1247    #[error(transparent)]
1248    QueryPlan(#[from] QueryPlanError),
1249    /// The external data source failed.
1250    #[error(transparent)]
1251    Source(#[from] SourceError),
1252    /// Provider data was incomplete.
1253    #[error(transparent)]
1254    Normalize(#[from] NormalizeError),
1255    /// A provider page violated its requested bounded range or canonical identity.
1256    #[error(transparent)]
1257    InvalidPage(#[from] SourcePageError),
1258    /// Provider blocks could not extend canonical history.
1259    #[error(transparent)]
1260    Canonical(#[from] CanonicalError),
1261    /// A page did not advance its exclusive cursor.
1262    #[error("source page made no progress from {from_block}: next_block={next_block}")]
1263    NoProgress {
1264        /// Query start.
1265        from_block: u64,
1266        /// Cursor returned by the source.
1267        next_block: u64,
1268    },
1269    /// No batch is currently awaiting acknowledgement.
1270    #[error("no delivery is awaiting acknowledgement")]
1271    NoPendingDelivery,
1272    /// The acknowledgement does not identify the in-flight batch.
1273    #[error("delivery token does not match the in-flight batch")]
1274    DeliveryTokenMismatch,
1275    /// A delivered batch unexpectedly omitted its cursor.
1276    #[error("delivered batch is missing its cursor")]
1277    MissingCursor,
1278    /// Internal rollback recovery was requested without an acknowledged guard.
1279    #[error("rollback recovery is missing its previous continuity guard")]
1280    MissingRollbackGuard,
1281    /// A fork affected only owner catch-up history, for which v1 has no scoped rollback control.
1282    #[error(
1283        "owner catch-up fork before activation block {activation_block} cannot be emitted as a global reorg (common ancestor {common_ancestor}, old tip {old_tip}, new tip {new_tip})"
1284    )]
1285    OwnerCatchupReorg {
1286        /// First block eligible for global canonical delivery in this revision.
1287        activation_block: u64,
1288        /// Last block shared by the displaced and replacement owner-only branches.
1289        common_ancestor: u64,
1290        /// Last block on the previously delivered owner-only branch.
1291        old_tip: u64,
1292        /// Last block on the observed replacement branch.
1293        new_tip: u64,
1294    },
1295    /// A service-generated control cannot pass an in-flight source delivery.
1296    #[error("cannot acknowledge an external control while a source delivery is pending")]
1297    PendingDelivery,
1298    /// A service-generated control attempted to move sequence backwards.
1299    #[error("delivery sequence regressed from {committed} to {received}")]
1300    SequenceRegression {
1301        /// Last committed sequence.
1302        committed: u64,
1303        /// Proposed sequence.
1304        received: u64,
1305    },
1306    /// The durable cursor was not the successor of its canonical checkpoint.
1307    #[error("resume cursor is {received}, expected canonical successor {expected}")]
1308    ResumeCursorMismatch {
1309        /// Successor implied by the canonical tip or provider guard.
1310        expected: u64,
1311        /// Persisted exclusive cursor.
1312        received: u64,
1313    },
1314    /// Provider-native resume metadata conflicted with the normalized canonical tip.
1315    #[error("resume provider guard conflicts with canonical `{0}`")]
1316    ResumeGuardMismatch(&'static str),
1317    /// The provider scan cursor advanced beyond the successor of preserved global coverage.
1318    #[error(
1319        "resume scan cursor is {received}, beyond preserved coverage successor {coverage_successor}"
1320    )]
1321    CoverageCursorMismatch {
1322        /// Successor of the preserved global coverage head.
1323        coverage_successor: u64,
1324        /// Persisted provider scan cursor.
1325        received: u64,
1326    },
1327    /// A rescan contradicted the exact block identity of preserved global coverage.
1328    #[error("rescanned canonical identity conflicts with preserved coverage at block {number}")]
1329    CoverageBoundaryConflict {
1330        /// Preserved boundary block number.
1331        number: u64,
1332    },
1333    /// The durable delivery sequence cannot advance without reusing a token.
1334    #[error("delivery sequence is exhausted")]
1335    SequenceExhausted,
1336    /// A canonical cursor could not represent the successor of the common ancestor.
1337    #[error("canonical block number cannot advance beyond u64::MAX")]
1338    BlockNumberOverflow,
1339    /// A canonical timestamp could not fit HyperSync's signed rollback-guard representation.
1340    #[error("canonical block timestamp {0} does not fit in i64")]
1341    BlockTimestampOverflow(u64),
1342    /// The configured delivery budget was zero or exceeded the protocol-safe maximum.
1343    #[error("delivery size limit {requested} must be within 1..={maximum} bytes")]
1344    InvalidDeliverySizeLimit {
1345        /// Requested limit.
1346        requested: usize,
1347        /// Largest safe adapter payload.
1348        maximum: usize,
1349    },
1350    /// Even the smallest provider page could not fit the configured wire budget.
1351    #[error("encoded delivery is {encoded_len} bytes, exceeding the {limit}-byte limit")]
1352    DeliveryTooLarge {
1353        /// Encoded protobuf delivery length.
1354        encoded_len: usize,
1355        /// Configured adapter limit.
1356        limit: usize,
1357    },
1358    /// A decoded provider response exceeded the independent hard local admission policy.
1359    #[error(
1360        "provider response contains {observed} {resource}, exceeding the hard limit of {limit}"
1361    )]
1362    ResponseLimitExceeded {
1363        /// Bounded resource.
1364        resource: &'static str,
1365        /// Decoded amount observed.
1366        observed: usize,
1367        /// Configured hard limit.
1368        limit: usize,
1369    },
1370}