fix(ai-explainer): address auditor findings from PR #226

[spalen0]

Follow-up to #226. The auditor's review landed after #226 was already merged, so these fixes need a separate PR.

Three findings — all valid:

P2.1 — Short-circuit `detect_proxy_upgrade` before decoding

Previously every call invoked `decode_calldata` before checking whether the selector was even an upgrade selector. For non-upgrade calls (which is most timelock alerts), an unknown selector miss could wait on the 30s Sourcify timeout for no reason.

Fix: selector membership check comes first; unknown selectors return None immediately.

Regression test patches `fetch_json` to raise and confirms no network call for a non-upgrade selector.

P2.2 — Show the proxy address in ProxyAdmin alerts

When the new ProxyAdmin path is detected, the tx `target` shown in the Telegram message is the ProxyAdmin — but the proxy actually being upgraded sits inside the calldata. Recipients couldn't tell which contract was changing without decoding the calldata themselves.

Fix: added a `🅿️ Proxy:` line when `upgrade.proxy_address != target`.

P2.3 — Recognize OZ storage-gap consumption as safe

Most serious finding. `_storage_layout` did naive slot-by-slot comparison and flagged the canonical OZ gap pattern as UNSAFE:

uint256 a; uint256[50] __gap;  →  uint256 a; uint256 b; uint256[49] __gap;

Slot 1 changed from `__gap` to `b`, so the original code flagged it. But this is the OpenZeppelin upgrade-safety primitive — almost every upgradeable contract has a trailing gap reserved exactly for this purpose. Without recognizing it, the tool would have produced false high-risk warnings on routine upgrades and recipients would have learned to ignore the warning exactly when it actually mattered.

Fix: detach trailing `gap` arrays before comparison, then validate that any new vars inserted before the gap correspond to a matching reduction in gap size. Still unsafe and flagged: gap underflow, no shrink while vars were inserted, gap removed without consumption.

Six new tests cover: consume-one, consume-many, underflow, no-shrink, full-consume, gap-removed-without-consumption.

Test plan

• `uv run ruff check .` passes
• `uv run pytest tests/test_impl_diff.py tests/test_proxy_upgrade.py` — 35 pass
• Full suite still passes locally
• Watch the next proxy-upgrade alert after merge to confirm the proxy address line renders and gap consumption no longer flags safe upgrades

🤖 Generated with Claude Code