refactor: dedupe the R2 witness adapters and hoist the jsonrpsee mock scaffolding

[flyq]

Summary

Two queued deduplications, in one PR:

• R2 witness adapters (follow-up from the feat(debug-trace-server): direct-from-R2 historical witnesses #175 review round — "Happy for this to be a follow-up"): the shared core of the two binaries' r2_witness.rs — the failure taxonomy (R2WitnessError, KINDS, kind()), the BackoffPolicy → RetryPacing conversion, transport construction, the target accessors, the blocking-decode error mapping, and the kinds_cover_all_fetch_kinds guard test (two copies protecting the same surface from the same drift) — now lives once in stateless_common::r2_witness. Transport construction happens at the two wiring sites that already own the flags and the metrics plumbing (main.rs / app.rs), which log the configured target straight off the transport; each adapter keeps a one-line new(transport) plus what genuinely differs: light-vs-full decode, deadline handling, retry budgets (3 vs 9), pacing pauses, and metrics hooks. New stateless-common → stateless-r2 dependency edge; acyclic, stateless-r2 stays a leaf crate.
• jsonrpsee mock scaffolding: three crates hand-rolled the same mock-upstream scaffold (ephemeral server bootstrap, minimal RPC header shapes, hex block-number parse). stateless_test_utils::mock_rpc now provides serve / serve_with_config, header_stub / consistent_header, and parse_hex_u64 — the mock_r2 precedent — and the specialized mocks in stateless-common, debug-trace-server, and the validator's integration tests build on it instead of re-rolling it. It sits behind an opt-in mock-rpc feature so stateless-core and stateless-r2 — dev dependents with no other jsonrpsee edge — do not compile the server stack for tests that never mock an upstream.

Behavior is pinned by the existing tests

This is a refactor; the discriminating tests are the ones that already existed, unchanged and green: the validator's pacing-pause tests (deterministic throttle + max-backoff pause before surfacing), both adapters' MAX_ATTEMPTS tests, the construction-rejection tests on both targets, the custom-domain bare-key/unsigned-GET assertions, and the cap-wiring test from #191 (the_r2_cap_not_the_rpc_one_reaches_the_transport, still asserting on both target arms that --witness-max-concurrent-requests 16 --r2-max-concurrent-requests 48 yields a cap of 48, so reverting either arm's wiring fails by value). Three per-binary tests collapse into one shared copy each — the KINDS guard and the two construction-rejection tests — which is the workspace count going 478 → 477.

The one observable change

The shared error union carries DecodeTimeout for both consumers, so the validator now pre-registers an r2_witness_errors_total{kind="decode_timeout"} series it can never produce (its fetches pass no deadline) — the same structurally-unreachable status as its existing deadline kind, now documented on the shared type.

Two deliberate deviations from the original dedup notes

• header_stub is not unified onto the self-consistent hash_slow() shape: the divergence-bisection tests must serve prescribed hashes (two chains differing only by hash), which a number-derived hash cannot express. Both shapes ship, each documenting which verify_hash paths accept it.
• serve_with_config exists alongside serve because the validator's fixture-backed mock needs max_response_body_size above jsonrpsee's default for its multi-MB witness payloads.

Testing

cargo test --workspace: 477 passed, 0 failed. fmt / clippy --all-targets --all-features / cargo sort clean; cargo check -p stateless-test-utils standalone (the crate's own build constraint) clean, and cargo tree -p stateless-core --edges dev -i jsonrpsee now resolves to nothing.

🤖 Generated with Claude Code

[mega-maxwell]

Claude review status

Living comment — rewritten in place. The review workflow keeps this single comment up to date instead of posting a new one each round, so it always describes the latest reviewed commit and the earlier text is intentionally gone. No reply is needed here; reply to a finding in its own review thread, and answer an open question in a reply on this PR. The next review round reconciles your answer.

🛠️ Review did not finish

Attempted 313ed680..44b9ee68 · updated 2026-08-27T15:41:08+00:00

This round did not publish: MODEL_ACTION_FAILED in phase review_retry. Anything listed below is from the last round that did. Re-run the workflow or push a new commit to try again.