feat: high-signal comparison output with expected-difference rules

[cbermudez97]

Summary

Implements the COMPARISON-IMPROVEMENTS.md handoff brief in full, motivated by a real archive-vs-archive Nethermind correctness run (v1.39.1 vs v1.40) where three problems dominated: expected differences (e.g. totalDifficulty, sub-1% eth_estimateGas drift) flooded the report, a single transport blip discarded an 800-call run, and the report was unopenable (~769 MB HTML).

Everything is backward compatible: new config blocks and flags are optional, and defaults reproduce prior behavior aside from the additive retry.

What's included

• Expected-difference rules — a unified comparison.rules list: ignore (with [*] array wildcards), numeric_tolerance (abs/rel on hex quantities), error_code_only, error_presence_only. eth_estimateGas gets a built-in 10% relative tolerance by default (diffs ≤10% treated as correct).
• Error classification — buckets namespace_disabled / no_state / range_cap so capability errors are filtered as config, not correctness.
• Retry + non-fatal transport — bounded retry with exponential backoff for transport errors and 5xx (honors clients.yaml max_retries, plus --max-retries / --retry-base-delay); a final transport failure is recorded per-call instead of aborting the whole run.
• Lean output — --diff-only, --omit-matching-responses, --max-response-bytes gate what comparison-results.json and the HTML serialize.
• Summary + CI gate — end-of-run category tally and --fail-on-diff exit code.
• Sync-gap awareness — --skip-above-head skips calls pinned above the lowest client head.
• Block pinning — block_override / --block-override rewrites latest/pending to a static block and appends a block arg to calls that omit one.
• Corpus helper — --from-jsonl / --sample builds a config from rpc-calls/*.jsonl with deterministic sampling and proof/head-dependent/debug exclusions.
• Provenance — the effective config is written to a comparison-provenance.json sidecar and surfaced in the report.

Files

New: runner/comparator/{rules,block_override,corpus}.go (+ tests). Modified: diff engine (threads a rules context), orchestrator, transport, config loader, report, and both CLI commands. Documented comparison: example added to config/compare/example.yaml.

Testing

• go build ./..., go vet ./... clean; comparator unit + integration tests pass (tolerance boundaries, ignore [*], error rules, classification, block-override rewriting, corpus sampling, retry-recovers, non-fatal transport, diff-only serialization).
• End-to-end CLI run against mock nodes: --diff-only kept only the real mismatch, the estimateGas drift was absorbed by the tolerance, provenance sidecar written, HTML small, --fail-on-diff exited non-zero.

Notes for review

• Gas tolerance direction: within 10% ⇒ equal/correct; >10% ⇒ reported.
• Rules / block_override / --from-jsonl are compare-only (they live in the compare YAML); retry, --diff-only, summary, --fail-on-diff, --skip-above-head apply to both compare and compare-openrpc.
• If the baseline client (Clients[0]) transport-fails on a call, the reference falls back to the first client that answered.