Phase 3: layered supply oracle

[jayeshy14]

Summary

Implements Phase 3 of the build plan (SPEC Section 13): the layered supply oracle. This is the central trust assumption of autonomous market-cap weighting, so it is built in three layers behind the ISupplyOracle seam, with the methodology engine never seeing how the number was secured.

Layer 1, minimize (ExcludedAddressRegistry)

• Derives circulating supply on-chain as totalSupply - Σ balanceOf(excluded), turning trust in a number into trust in a publicly auditable list of addresses.
• totalSupply is a free trustless upper bound; the subtraction fails closed on underflow.
• Every excluded-set change is timelocked (1 hour to 30 day band), visible before it takes effect, permissionless to execute once the delay elapses, and cancellable before.

Layers 2 and 3, secure and contain (SupplyOracle)

• freeFloat = onChainCirculating * freeFloatFactor / 1e18, with the factor capped at 1e18, so free-float can never exceed the on-chain floor by construction.
• Layer 2 divergence freeze: a commit takes the median of fresh reporter values and requires k of them to agree within tolerance; otherwise it reverts and the constituent stays frozen at last-good rather than acting on disputed data.
• Layer 3 containment: a per-commit rate-limit clamps large moves so a spike is approached gradually over several commits; a hard maxCommitAge fails reads closed; the guardian can pause all reads.
• Interface-shaped so an optimistic oracle can replace the residual source per constituent later without touching the methodology.

Design notes

• Freeze vs revert: because supply is the slow input (price, the fast one, is Chainlink's job), soft staleness and source divergence freeze and serve last-good; a revert is reserved for hard failures (paused, uninitialized, past the hard ceiling). The ISupplyOracle doc was updated to state this contract.
• Rate-limit clamps rather than rejects: rejecting a too-large commit never converges (every commit re-sees the full median); clamping toward the median by one step per commit is what makes "approached gradually" actually work.

Testing

26 new tests, 75 passing total. Covers the timelock lifecycle, on-chain derivation, the median commit path, adversarial divergence freeze, rate-limit clamp convergence, hard and soft staleness, guardian pause, and an end-to-end integration driving MarketCapMethodology through the real layered oracle (no mock supply source in the path).

Two behaviors surfaced and confirmed correct: at n = 1/cap the capped index saturates to equal weight and every name becomes supply-insensitive (a stronger form of SPEC 8.4), and excluding a name's entire supply can trip the CapInfeasible guard by dropping the nonzero count below 1/cap.