docs(derivation): stateException is only from verifyBatchRoots

[curryxbo]

Summary

Comment-only. BatchStatus=stateException is set solely at the verifyBatchRoots call site; the rebuildBlob failure path logs and retries without reading ErrBatchVerifyDivergence.

• verify.go: the sentinel doc listed a versioned_hash_mismatch kind rebuildBlob never returns, and said "call sites" (plural) gate stateException.
• verify_local.go: the rebuildBlob doc claimed blob_count_mismatch makes the call site flip stateException, and referenced a SentinelContract test that does not exist.
• metrics.go: LocalVerifyTriggered doc claimed local-verify failures propagate to BatchStatus=stateException.

No behavior change: blob_count_mismatch still wraps ErrBatchVerifyDivergence.

Test plan

• Confirm derivation.go gates SetBatchStatus(stateException) only after verifyBatchRoots

[claude]

Claude Code Review

Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 63ac426d-acbc-4aaf-956e-1a9019106ed3

📥 Commits

Reviewing files that changed from the base of the PR and between fbb298a and 95e62bc.

📒 Files selected for processing (3)

• node/derivation/metrics.go
• node/derivation/verify.go
• node/derivation/verify_local.go

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change clarifies local verification error semantics. Blob count mismatches now return plain errors, while only root divergence can set BatchStatus=stateException.

Changes

Local verification semantics

Layer / File(s)	Summary
Divergence contract and status semantics node/derivation/verify.go, node/derivation/metrics.go	The documentation limits ErrBatchVerifyDivergence to state or withdrawal root mismatches. Local verification failures are represented by error logs.
Blob mismatch handling node/derivation/verify_local.go	blob_count_mismatch is documented and returned as a plain error. It no longer wraps ErrBatchVerifyDivergence.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 95e62

The change clarifies derivation status behavior and keeps blob mismatches on the retry path while reserving stateException for verified root divergence. No actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: dylancai9, twcctop

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: documenting that stateException is set only from verifyBatchRoots. It also matches the related error-handling change for blob_count_mismatch…

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files.

Full details: Title check

Explanation

The title clearly and concisely identifies the main change: documenting that stateException is set only from verifyBatchRoots. It also matches the related error-handling change for blob_count_mismatch.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/clarify-state-exception-sentinel

---

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.}