[rymnc]

Breaking: Source::head returns BlockRef, SnapshotSink::reset is required, DivergenceCause::ForkBeyondWindow is removed. Bumps to chainfold 0.4.0.

• Trust boundaries: decode refuses a cursorless snapshot that carries a ring. Checkpoint slots are capped at 1 << 16. Only the engine's own offer can move the durable watermark. A queue depth of 0 no longer blocks.
• Panics poison: a caught Fold::apply panic poisons the engine instead of leaving a half-applied span. Poisoned engines refuse to encode. Caught up is false unless Active.
• Rollback and reset bookkeeping: a rollback drops every checkpoint newer than the restored cursor and rewinds the write position. Cadence marks are clamped each tick. Sinks reset with the engine. A recovered engine checkpoints at the recovery point.
• One chain per fold: the scan reads the head first, and every batch must match it. Torn answers, out-of-window entries and two hashes at one height are refused. A head below the cursor is Idle, not a fork. The walk stops at u64::MAX.
• Bounded walks: a tick reads at most span windows (starts at 64, halves on error, doubles otherwise). A long empty walk keeps its progress, so a first sync finishes under rate limits.
• Docs and tests: README fork/terminal semantics corrected. apply_alloc counts per thread. ScriptedChain::events_in includes u64::MAX.

[Copilot]

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

[oskarth]

The lagging shortcut in scan (driver.rs:578) only checks the ring for a block at the head's height, but the ring holds event and boundary blocks only. With events at 10 and 20 and a fork that replaces 10..20 with a chain ending at 15, every tick is Idle with caught_up = true and the orphaned events stay folded until the fork outgrows 20. Suggest confirming the newest observed block at or below the head with one header_at before returning Lagging (one extra read per lagging tick; a_head_below_the_mark_is_idle_and_changes_nothing then expects 2 reads), and documenting the residual window in the scan doc comment.

Repro, passes on this branch as crates/chainfold/tests/lagging_repro.rs:

use chainfold::{Driver, DriverConfig, EngineConfig, Position, Tick, test_util::{RecordingFold, ScriptedChain}};

#[test]
fn a_shorter_fork_with_no_ring_entry_at_its_head_is_reported_idle() {
    // given events at blocks 10 and 20 only, folded to block 20
    let mut chain = ScriptedChain::new(1);
    for n in 1..=20u64 {
        let events: Vec<u64> = if n == 10 || n == 20 { vec![n] } else { vec![] };
        chain.push_block(&events);
    }
    let config = EngineConfig { ring_capacity: 64, checkpoint_slots: 4 };
    let mut driver = Driver::new(RecordingFold::default(), chain, config, DriverConfig::from_block(1)).unwrap();
    while driver.tick() != Tick::Idle {}
    assert_eq!(driver.engine().cursor(), Some(Position::new(20, 0)));
    // when blocks 10..=20 are replaced by a fork ending at 15, with an event at 12
    let blocks: Vec<Vec<u64>> = (10..=15u64).map(|n| if n == 12 { vec![12] } else { vec![] }).collect();
    let replacements: Vec<&[u64]> = blocks.iter().map(Vec::as_slice).collect();
    driver.source_mut().reorg(11, &replacements);
    let ticks: Vec<Tick> = (0..5).map(|_| driver.tick()).collect();
    // then every tick is Idle, caught_up is true, the orphaned events stay, 12 is never folded
    assert!(ticks.iter().all(|t| *t == Tick::Idle), "{ticks:?}");
    assert!(driver.status().caught_up);
    let applied: Vec<u64> = driver.engine().fold().applied.iter().map(|(_, e)| *e).collect();
    assert_eq!(applied, vec![10, 20]);
}

[rymnc]

addressed in 9cb78f8 @oskarth