fix(chainfold): manual review fixes

[rymnc]

Note

chainfold costs ~0.33 ns per event in steady state (3.1 G events/s on my machine) effectively free next to the RPC that fetched the logs, and in exchange gives us total ordering, idempotent replay, fork detection with rollback, and crash-safe restart from a durable snapshot in 3.7 ms for a million-entry state.

This pull request refactors and simplifies core validation, checkpoint, and driver logic in the chainfold crate, improving clarity, correctness, and maintainability. The most notable changes include a significant rewrite of batch validation, simplification of checkpoint ring iteration, consolidation and improvement of driver rollback and checkpoint logic, and minor cleanups in the engine. Below are the most important changes grouped by theme:

Batch Validation Improvements

• The Batch::validate method was rewritten for clarity and correctness. It now uses a previous-span tracker to check for contiguous spans, simplifies bounds checks, and efficiently checks log index ordering within spans. This reduces code duplication and potential for errors.

Checkpoint Ring Refactoring

• Introduced a new oldest_first iterator in CheckpointRing to simplify and unify slot iteration logic, which is now used in count, oldest, and best_at_or_below methods. The clear and drop_above methods were also simplified to use more idiomatic Rust. [1] [2]

Driver Logic Simplification and Consolidation

• Refactored driver methods to use new helper functions and idioms:
  • Replaced manual option matching with .is_none_or() and .is_some_and() for checkpoint and snapshot due logic. [1] [2]
  • Centralized rollback logic into a new roll_back_to method, reducing code duplication and making error handling more consistent. [1] [2]
  • Improved backoff calculation to use saturating arithmetic and clarified the logic.
  • Simplified snapshot mark clamping using .zip() and .map().
  • Changed the order of checkpoint and snapshot offering so that checkpoint ticks override snapshot ticks, which override progress ticks.
  • Removed several unused or redundant public constructors for driver types, reducing API surface. [1] [2] [3]
  • Improved handling of replay horizon edge cases, ensuring proper error escalation.

Engine Cleanups and Minor Fixes

• Removed the unused config field from Engine, and updated methods accordingly. [1] [2]
• Updated fork detection error reporting to take block number and hash directly, reducing unnecessary struct construction. [1] [2]
• Clarified documentation and logic for checkpoint restoration, ensuring checkpoints between the fork boundary and the restored cursor remain valid.
• Updated Engine::reset to clear the block ring instead of recreating it, preserving allocation.
• Simplified span application logic in apply_span, ensuring both accepted and skipped events advance the cursor, and deduplicating code.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.