test(invariants): totalSupply tracks net mints across mint/burn cycles (closes #25)

[abhicris]

Summary

Adds the first invariant-style test for Stablecoin.sol. A Handler contract bounds fuzz inputs to legal sequences of mint / burn / burnFrom against three pre-seeded actors, and ghost-tracks cumulative mints and burns. The invariant then asserts that on-chain totalSupply always equals the net ghost mints minus burns.

Closes #25.

Why invariants here

Unit tests in Stablecoin.t.sol already cover mint/burn at known endpoints. What they miss: any regression that causes totalSupply to drift from the sum of balances across random sequences. Examples this catches that unit tests don't:

• A _mint that emits the right event but skips the balance write
• A burnFrom path that decrements balance twice in some edge case
• An admin role mistake that lets non-MINTER mint into ghost-only state

What's asserted

Invariant	Why
totalSupply() == ghostMinted - ghostBurned	The core ledger consistency
sum of per-actor balances == totalSupply	No silent balance leaks into unreachable addresses
invariant_callSummary (visibility)	Surfaces per-action call counts at -vv so a run that minted-but-never-burned is detectable in CI

Handler design

• targetContract(address(handler)) + explicit targetSelector list — restricts fuzzing to handler_mint / handler_burn / handler_burnFrom. Without that, the fuzzer wanders into pause(), grantRole(), etc. and most calls revert in setUp, eating the budget.
• Three actors pre-seeded (0xB1, 0xB2, 0xB3) so burn paths fire from call 1.
• Mint amount bounded to [0, 1e30] — generous headroom (1e24 INV at 6 decimals) while preventing uint256 overflow at the high tail of the run × depth budget.
• Burn paths gracefully no-op when the chosen actor has zero balance — so fuzzer cycles aren't wasted.

Verifying it catches bugs

Per acceptance criteria, the test must fail when accounting is intentionally broken. To verify locally:

1. In contracts/Stablecoin.sol, change _mint(to, amount) in mint() to _mint(to, amount + 1) (introduce drift).
2. Run forge test --mt invariant_totalSupplyMatchesNetMints -vvv.
3. Expected: invariant fails with Stablecoin accounting drift: totalSupply != net mints.
4. Revert the change.

Test plan

• CI: existing forge test -vvv job passes (forge-test/invariants is under FOUNDRY_TEST already)
• Manual: invariant fails when accounting is intentionally corrupted (see above)
• Manual: run summary at -vv shows non-zero counts in all three call types (mint / burn / burnFrom)