fix(llm): derive impl diffs from ABIs and compiler storage layouts

[spalen0]

Closes #367.

The problem

The implementation-diff enrichment ran regexes over the concatenated Etherscan bundle, so it could not tell the deployed contract from its bases, libraries and imported interfaces. On the 3Jane USD3/sUSD3 upgrade it produced the same eight "additions" for both proxies — six were USD3 functions, two were IMorpho interface declarations — described clearMarketWindDown as an unpermissioned function on USD3/sUSD3 (it lives on MorphoCredit and is onlyOwner), reported a commented-out restartStrategy() as removed, missed sUSD3's only real change, and called storage safe because an imported library uses namespaced storage.

What changed

Every fact is now target-scoped and carries provenance, in four separated categories.

Category	Source of truth
External ABI changes	each implementation's own verified ABI, keyed by canonical signature
Changed function bodies	the deployed contract's own definition in its own file, with a unified diff
Storage compatibility	compiler storageLayout from Sourcify, for both sides
Unvalidated items	stated explicitly, so silence is never read as safety

• Structured record (utils/verified_contract.py) replaces the flattened cache tuple: per-file sources, compiler settings, ABI, and a resolved compilation target (settings.compilationTarget, else the unique declaring file). The disk-cache namespace carries the schema version, since positive source entries never expire. Concatenation survives only as an explicitly named search helper for natspec.
• Storage (utils/sourcify_layout.py, utils/storage_layout.py) is now COMPATIBLE / INCOMPATIBLE / UNKNOWN. Slot, byte offset and recursive type shape are compared; compiler-internal type/AST ids and variable names are not, so a rename at an unchanged slot is context rather than a conflict. One-sided Sourcify coverage, a match: null response, a malformed payload or an ERC-7201 target all yield UNKNOWN — never a soft COMPATIBLE. No compiler is downloaded or executed in the monitoring path, per the follow-up in the issue.
• Bodies (utils/solidity_text.py) are compared inside the deployed contract's braces only. Ambiguous target resolution or ambiguous overloads report the analysis unavailable instead of searching the bundle.
• Risk anchor: upgradeToAndCall / upgradeAndCall now read their bytes argument — an empty payload replaces the implementation and nothing else, rather than always claiming an initializer ran.
• Prompt guardrails: the system prompt scopes each category, and says that UNKNOWN storage is neither safe nor unsafe, that internal/private functions are not a governance control surface, and that a source-level modifier is not an authorization proof.
• Consistency gate: every claim is re-derived from its own ABI before the prompt sees it; a section that fails is withheld and logged. If two contracts in one process get the same additions, the diff says so inline and logs a warning but keeps the result — each set was proven against its own ABI, so two siblings genuinely gaining the same function is a real finding.

Verification

Every failure mode from #367 is covered by synthetic, protocol-neutral fixtures (no frozen contract bundles in the repo), including: duplicate signatures across interface/base/target, comment-borne function text, commented-out code, overloaded tuple/array signatures, body-only and moved-into-helper changes, packing and offsets, structs spanning slots, safe renames, correct and over-consumed gaps, same-width retypes, custom value type resolution, ERC-7201 roots (checked against OpenZeppelin's and EIP-1967's published constants), and missing/unmatched/malformed/one-sided Sourcify responses.

The behavior was also checked by hand against the real 3Jane USD3/sUSD3 upgrade that motivated the issue: USD3 gets exactly its 7 ABI additions and 10 removals with a compatible positional layout, and sUSD3 gets no surface change plus its availableDepositLimit body change. Those bundles were not committed — the tooling is general, not tied to one protocol.

Note for review

Sourcify coverage is narrower than Etherscan's, so some upgrades will report UNKNOWN storage where the old code printed a (sometimes wrong) verdict. That is the intended trade: the issue's acceptance criterion is that storage is never called compatible without matched compiler layouts for both implementations.

Not included, flagged in the issue as P2/P3: an independent ERC-7201 namespace validator (namespaced targets are UNKNOWN until it exists), and letting the detail stage downgrade a summary — that fights the deliberate two-stage design where the TLDR is authoritative, so it seemed worth deciding separately.

🤖 Generated with Claude Code

[spalen0]

Verified against PR head 11d98884b10ae2813060777f1eac1d08daca1bbd. Both stated limitations are present. I recommend fixing the verdict/coverage handling first, then adding bounded type and storage-access resolution while preserving #367's requirement that the monitoring runtime never downloads or executes a compiler.

Verification

The focused suite passed: 95 tests, 14 subtests across test_storage_layout.py, test_namespaced_storage.py, test_impl_diff.py, and test_impl_diff_3jane.py.

Additional synthetic reproductions exercised the actual comparison functions, mocking only the fetched compiler-layout boundary:

Case	Current result	Required behavior
type Id is bytes32 replaced with bytes32, same placement	INCOMPATIBLE	Compatible storage representation once the underlying declaration is resolved; otherwise UNKNOWN
Same name Id, underlying declaration changes bytes32 → uint256, same width	COMPATIBLE	Detect the reinterpretation once resolved; otherwise UNKNOWN
Target calls an internal library accessor; library storage member changes uint256 → bytes32	COMPATIBLE, no collected namespaces	Include the used library storage in coverage; unresolved comparison means UNKNOWN
Unannotated storage accessor changes its root	COMPATIBLE, no collected namespaces	Include the accessor in coverage and detect a proven root change
Annotated namespace keeps identical struct text but its accessor changes root	COMPATIBLE, namespace reported unchanged	Verify the actual storage root as well as the struct

The relevant paths are _type_kind, collect_namespaces / _unvalidated_reason, and _compare_storage. The generic “Unvalidated items” text currently does not affect the storage verdict.

Artifact availability changes the proposed approach

I checked the live Sourcify v2 response for new USD3. It returns a verified match and 35 source entries in stdJsonOutput, zero containing an AST. The separate sources field does include type Id is bytes32; in src/interfaces/IMorpho.sol. The old USD3 layout describes Id only by label, encoding, and width.

Consequently, “fetch the AST from Sourcify” is not a sufficient implementation plan for this regression. Prefer a matching compiler AST when available, but support a deliberately bounded parser/resolver over verified source. Do not silently start compiling in the cron.

Proposed implementation plan

1. Separate evidence from coverage. Extend comparison results to retain both proven conflicts and unresolved storage evidence. Aggregate as: any proven conflict → INCOMPATIBLE; otherwise incomplete storage coverage → UNKNOWN; otherwise → COMPATIBLE. Keep the positional result visible separately. Do not downgrade storage for unrelated omissions such as modifier-body analysis. Until storage reachability can be established, explicitly report that coverage as unresolved rather than treating an empty namespace collection as proof of absence.

2. Resolve UDVT declarations on each side. Use source-qualified declaration identities, import aliases/remappings, and lexical scope to resolve type X is T; never use a bundle-global name match. Use compiler AST references when supplied with the same build, or a token/parser-based resolver for supported source forms. Normalize to the underlying elementary kind recursively through mapping keys/values, arrays, and struct members, while retaining the original type for display. Preserve compiler-reported slot, offset, encoding, and width checks, and the existing contract/address equivalence. Unresolved UDVTs must not compare equal merely because their names match. Report wrapper removal/renaming as context, not proof of behavioral safety.

3. Discover actual storage access from the target. Extend beyond inheritance to resolved library calls and storage references passed into helpers, including using ... for. Find annotated structs and unannotated storage-pointer assignments such as s.slot := ROOT; track raw sload/sstore and unresolved delegatecalls as uncovered storage access. Merely importing a library must not add its storage to the target. Unsupported calls or ambiguous resolution must retain an explicit coverage gap.

4. Validate roots before claiming namespaces unchanged. Resolve supported literals/constants and well-defined hash expressions, confirm that an ERC-7201 accessor uses its annotated root, and compare old/new root plus member layout. Detect duplicate roots and provable overlaps. Use compiler-derived struct layouts where available; ASTs alone do not guarantee emitted namespace layout data. Without such layouts, limit any unchanged proof to forms whose root, type dependencies, and compiler layout behavior are established. Changed or unsupported structures remain UNKNOWN. A broader namespace-layout engine or separately generated, build-bound artifacts should be a follow-up, not an implicit compiler fallback.

Regression / acceptance plan

• UDVT unwrap/rewrap, rename, same-name underlying-type change, nested containers, duplicate names/import aliases, missing declarations, and compiler-version packing differences.
• Used versus merely imported libraries; inherited and unannotated accessors; unchanged struct with changed root; annotation/root mismatch; duplicate roots; unresolved dynamic roots and delegatecalls.
• Verdict precedence: a proven conflict remains INCOMPATIBLE even when another region is unknown; incomplete storage coverage never produces an unqualified COMPATIBLE.
• Keep the existing 3Jane ABI/body/positional-layout regressions. USD3's positional layout can remain compatible even if the combined verdict becomes UNKNOWN until library storage coverage is established.
• Freeze artifact payloads, including the no-AST case, and verify that the new regression assertions fail on this PR head before implementing the fixes. No compiler download/execution and no new network dependency in unit tests.

The Solidity docs support normalizing UDVTs to their underlying representation, but actual compiler layout checks remain necessary because of historical UDVT packing differences. ERC-7201 explicitly leaves enforcement of the declared namespace to the developer, which is why identical annotations/structs alone cannot establish root stability.