chore(ethexe): create create level doc for ethexe-consensus, ethexe-processor, ethexe-compute

[grishasobol]

created by @claude, but fully review, fixed and modified by @grishasobol

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
ethexe/consensus/src/lib.rs	2% smaller
ethexe/compute/src/lib.rs	0% smaller
ethexe/processor/src/lib.rs	0% smaller

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces detailed crate-level documentation for three core components of the ethexe stack. The new documentation provides high-level architectural overviews, explains the role of each crate within the system, details entry points, and outlines critical design considerations for future development.

Highlights

• Documentation: Added comprehensive crate-level documentation for ethexe-compute, ethexe-consensus, and ethexe-processor to improve developer onboarding and maintainability.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the internal documentation of the ethexe workspace by adding detailed module-level comments to the compute, consensus, and processor crates. These updates provide a clear overview of each crate's role, entry points, and internal pipelines. The review feedback focuses on correcting minor typos and refining technical terminology to ensure clarity regarding consensus-sensitive logic.

[grishasobol]

@claude opus review

[claude]

Claude finished @grishasobol's task in 3m 59s —— View job

---

Claude Opus Review

• Read styleguide and CLAUDE.md guidance
• Read the three new crate-level docs
• Cross-check claims against ethexe-compute, ethexe-consensus, ethexe-processor, ethexe-common, and lazy-pages source
• Post review

Summary

Documentation-only PR that adds substantial crate-level docs to ethexe-compute, ethexe-consensus, and ethexe-processor. Quality is high: the docs accurately describe the event flow, the validator state machine, the overlay execution semantics, the chunked parallel executor's "max-gas-in-chunk" charging rule, and the producer/quarantine model — all of which I verified against the source. The "When modifying this crate" sections are particularly valuable because they pin down invariants that aren't visible from the code (e.g. promise collection only during the injected pass, no wall-clock leakage into producer election, processor must never write to KV storage). The author has already addressed the typo/wording comments from Gemini.

A few accuracy/clarity points below. None of them block — they're worth fixing now while the docs are fresh.

---

severity: medium — Lazy-pages mechanism description has it backwards

File: ethexe/processor/src/lib.rs lines 116-122

Pages are protected after instance setup and loaded from the database on first access (via a page fault on Linux / a signal-driven mechanism on other platforms), through the gear_lazy_pages integration.

The two halves of the parenthetical contrast aren't actually different things, and the labels are inverted. Looking at lazy-pages/src/sys/:

• unix.rs registers a SIGSEGV signal handler via nix::sys::signal — Linux is the signal-driven path.
• windows.rs registers a Vectored Exception Handler via AddVectoredExceptionHandler for EXCEPTION_ACCESS_VIOLATION — that's SEH, not a POSIX signal.

Both are triggered by an underlying page fault; the differentiator is signal vs. structured exception. Suggested rewrite:

//! Pages are protected after instance setup and loaded from the database on
//! the first access fault — delivered as SIGSEGV on Unix and as a vectored
//! structured exception on Windows — through the [`gear_lazy_pages`] integration.

Fix this →

---

severity: low — process_programs contract omits that stage 3 is conditional

File: ethexe/processor/src/lib.rs lines 62-91

The section enumerates three sequential stages and says the result is always a FinalizedBlockTransitions. But in Processor::process_programs (lines 310-344) stage 3 only runs if gas_allowance.is_some():

if let Some(gas_allowance) = gas_allowance {
    transitions = self
        .process_queues(transitions, block, gas_allowance, promise_out_tx)
        .await?;
}

If callers ever pass None (e.g. some test paths use it; ExecutableData exposes the field as Option<u64>), only stages 1 and 2 run. A one-liner like "stage 3 is skipped entirely when gas_allowance is None" would keep the doc honest about what the API actually does.

---

severity: low — Quarantine "genesis is the floor" is opaque without explaining what "floor" means

File: ethexe/compute/src/lib.rs lines 117-123

The current text says compute reads events from "an ancestor that is canonical_quarantine blocks older (the genesis block is the floor)". Reading find_canonical_events_post_quarantine (compute.rs:373-400), the actual behavior when the requested walk crosses genesis is that it returns Default::default() (empty Vec<BlockEvent>) — i.e. for blocks shallower than canonical_quarantine from genesis, the runtime sees no events at all, not the events at genesis. Worth saying that explicitly:

When the walk would pass genesis, the returned event list is empty — i.e. for the first canonical_quarantine blocks after genesis the runtime sees no Ethereum events.

---

severity: low — Two minor consensus-section nits worth fixing while you're in there

File: ethexe/consensus/src/lib.rs

• Line 168: NOTE: the only wall-clock logic the crate runs is … — the prose tail of the same sentence repeats the wall-clock point in the "When modifying" section (lines 196-201). One mention is enough; consider deleting the NOTE: here since the invariant section is the load-bearing one.
• Lines 78-87 entry-points table reads well, but the entries receive_synced_block / receive_prepared_block / receive_computed_announce are described as "the block's data is now available" / "the block is now prepared" / "an announce has finished executing". For someone who hasn't read ethexe-compute yet, a half-clause naming the upstream producer (observer / compute / compute) would shorten the time to context. Optional.

---

What I checked and found accurate (no action needed)

• Validator state diagram (Initial → Producer → Coordinator → Initial / Initial → Subordinate → Participant → Initial) matches ethexe/consensus/src/validator/mod.rs:27-40.
• "Block gas allowance counter is charged by the maximum gas spent in the chunk, not the sum" — matches chunk_execution_processing.rs:46-49,66.
• "Promises are collected only during the injected pass; the canonical pass runs with the promise sender dropped" — matches run/mod.rs:380-393 (disable_promises then Canonical pass).
• "Ancestors are always computed without promise collection regardless of the requested policy" — matches compute.rs:135-138 (loop passes None for promise_out_tx).
• ConsensusEvent::PublishPromise going to both RPC and network — matches service/src/lib.rs:692-704.
• ProtocolTimelines, ValidatorConfig::producer_delay, ValidatorConfig::signatures_threshold, and CANONICAL_QUARANTINE all exist where the docs claim.
  · branch: gsobol/ethexe/docs

[claude]

Summary

Adds comprehensive module-level documentation to three ethexe crates (compute, consensus, processor), replacing one-liner stubs with detailed architectural contracts, entry-point tables, event-flow summaries, and "When modifying this crate" constraint sections. No code changes.

Findings

No issues found.

The docs are internally consistent and match the known architecture. Two observations worth noting for future reference:

• The compute docs make strong liveness claims ("the stream eventually yields exactly one … or a ComputeError") that accurately describe the existing implementation contract but are not machine-checked by any test. Worth keeping in mind during future refactors of the compute pipelines.
• The processor "When modifying" section calls out that the processor must write only to CAS and never to KV storage — a critical determinism invariant. A lint or assertion enforcing this at CI time would be valuable, but is out of scope for a docs PR.

---

After pushing new commits, comment /review-delta to get an incremental review.