Correct canonical witness lookup and null handling for v2.2.1

[0xBreadguy]

Summary

The witness guide and RPC reference describe number-only requests as returning the first stored witness and tell clients to treat missing witnesses as errors. In mega-reth v2.2.1, number-only requests resolve the local canonical hash, return only a matching witness, and return result: null if the canonical hash or matching witness is unavailable.

• Replace first-row/unsafe lookup guidance with canonical resolution and retry-after-catch-up behavior.
• Document nullable results and reserve -32603 for internal failures; remove the missing-witness error-message matching advice.
• Explain that explicit hash/payload selectors are unchanged and pin identity without guaranteeing continued canonicality.
• Make the operator decoding example stop on null and RPC errors before decoding.

Addresses F-001. Verified against megaeth-labs/dist-docs#55, megaeth-labs/mega-reth#2026, and the executable handler in v2.2.1/crates/megaeth/rpc/src/witness.rs. The handler's old selection-priority comment still mentions the fallback, but its implementation and regression test explicitly remove it. Missing-witness null is an existing response contract; the release change removes the unknown-canonical first-row fallback.

Validation

• Repository-wide Markdown lint and Prettier 3.8.5 pass.
• JSON examples parse; local file links and GitBook blocks validate.
• Bash example passes syntax validation; its jq guard accepts available results and rejects null/error responses without emitting a payload.
• git diff --check passes.
• No live witness requests issued; behavior verified against the release-tagged source. Repository CI passes, including link checks and PR review pipeline tests.

[0xBreadguy]

Did this as part of the latest security advisory (p0).

The callout was verified and then I had this PR submitted by my agent (using Astra).

Did it to be helpful, but need the team to validate. If this just creates noise I'll confine PRs to my own working sections (e.g. tokenlist)