fix(derivation): clamp deriveForce skipNumber to batch tip

[curryxbo]

Summary

Targets the CodeRabbit review comment on #966 (r3340287543).

In deriveForce, skipNumber >= rollupData.lastBlockNumber is reachable due to a small race between scenario-C dispatch and reactor quiesce; without a guard it returns a header past the batch tip and corrupts downstream verifyBatchRoots / advanceSafe.

Why the race exists

scenario-C entry in derivationBlock is decided before withReactorsQuiesced stops the blocksync / broadcast reactors:

T0: HeaderByNumber(lastBlockNumber) → nil   // dispatch decision, P2P alive
T0..T1: fetchRollupDataByTxHash(...)         // L1 RPC, P2P still alive
T1: withReactorsQuiesced.preWrite read
T1+: StopReactorsBeforeReorg()              // P2P stops here
T2: body() reads localLatest                 // skipNumber = this value

Between T0 and T1+, blocksync can deliver blocks up to and past lastBlockNumber (peers already hold them; we were just lagging). localLatest read at T2 reflects that catchup, so skipNumber >= lastBlockNumber is physically reachable even though it should not be by the dispatch logic.

l2Grew is a coarse cross-poll growth signal — single misjudgements are tolerated by design. The clamp here is what makes that tolerance actually safe at the deriveForce layer.

Symptom without the fix

When the race materialises:

1. The block loop's if blockData.SafeL2Data.Number <= skipNumber { continue } skips every block.
2. deriveForce returns header(skipNumber) — a block strictly past rollupData.lastBlockNumber.
3. verifyBatchRoots(batchInfo, lastHeader) compares the batch's expected post-state / withdrawal roots against a later block → mismatch → SetBatchStatus(stateException) (spurious alarm).
4. tagAdvancer.advanceSafe(batchIndex, lastHeader) pushes safe head past the batch tip → (batchIndex, safe) association is wrong.

Fix

Add an early return in deriveForce when skipNumber >= rollupData.lastBlockNumber:

• Read header(rollupData.lastBlockNumber) from the local node (it must exist by definition of the race).
• Return it directly. Upstream now sees the same header that scenario A would produce if the dispatcher had observed the now-present batch tip.

The early return runs inside withReactorsQuiesced's body, so the deferred StartReactorsAfterReorg still fires — reactors are restarted normally.

Test plan

• Unit-test or manual trace verifying that a BatchInfo with lastBlockNumber <= skipNumber returns header(lastBlockNumber) and writes nothing.
• Manual or integration scenario where blocksync catches up between dispatch and quiesce: confirm no stateException is raised and safeHead matches batchInfo.lastBlockNumber.
• Existing scenario B (skipNumber==0) and scenario C with a true gap (skipNumber < lastBlockNumber) still write blocks as before.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b5891744-027d-449e-b150-94d5ffe89e82

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/derive-force-clamp-skipnumber

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}