feat(revenue_pool): add per-entrypoint auth snapshot test for #888

[Dprime2]

Summary

Closes #888

Adds a per-entrypoint auth snapshot test for the revenue_pool contract. The
test enforces that every state‑changing entrypoint calls require_auth and
every read‑only entrypoint (and pure helper) does not, with a snapshot
inventory assertion that fails loudly if the documented auth surface shrinks or
grows without a matching test update.

The change is confined to a single file:

• contracts/revenue_pool/tests/auth_snap.rs

What this PR does

1. Re-organises the header docstring. The existing test file already
   contains a per-entrypoint *_requires_auth test for every mutator and a
   *_does_not_require_auth test for every view + the chunk_iter helper.
   This PR only augments the documented surface:

   • New ## Overlap with emergency_auth_snap.rs section that explains why
     the four emergency-drain entrypoints are intentionally re-covered
     here (the dedicated tests/emergency_auth_snap.rs suite focuses on
     timelock semantics + non-admin rejection — not auth surface).
   • New ## Snapshot inventory section explaining how the invariant is
     pinned.
   • Closes CalloraOrg/Callora-Contracts#888 footer.

2. Adds the auth_snap_covers_expected_entrypoint_counts test that
   pins the documented auth surface with three non-tautological
   buckets:

   EXPECTED_MUTATING_ENTRYPOINTS = 19   // init, set_admin, accept_admin,
                                         // claim_admin, cancel_admin_transfer,
                                         // set_pause_guardian, clear_pause_guardian,
                                         // pause, unpause, receive_payment,
                                         // deposit_yield, set_max_distribute,
                                         // distribute, batch_distribute,
                                         // upgrade, broadcast,
                                         // propose/execute/cancel_emergency_drain
   EXPECTED_VIEW_ENTRYPOINTS    = 12    // get_admin, get_usdc_token,
                                         // get_pending_admin, get_pause_guardian,
                                         // is_paused, get_cumulative_yield_deposited,
                                         // get_max_distribute, balance, get_version,
                                         // version, get_storage_ttl,
                                         // get_pending_emergency_drain
   EXPECTED_HELPER_ENTRYPOINTS  = 1     // chunk_iter (pure helper)
   

   The split intentionally separates the pure helper (chunk_iter) from
   the read-only views so the next auditor can see the breakdown at a
   glance. Mirrors contracts/migrate/tests/auth_snap.rs's
   auth_snap_covers_expected_entrypoint_counts invariant family.

Coverage of existing auth surface

Category	Entrypoints	# Requires	# No-auth
Initialization	init	1	0
Admin rotation (2-step)	set_admin, accept_admin, claim_admin, cancel_admin_transfer	4	1 (get_pending_admin)
Pause guardian	set_pause_guardian, clear_pause_guardian	2	1 (get_pause_guardian)
Circuit breaker	pause, unpause	2	1 (is_paused)
Yield management	receive_payment, deposit_yield, set_max_distribute	3	2
Distribution	distribute, batch_distribute	2	0
Upgrade / broadcast	upgrade, broadcast	2	0
Emergency drain	propose_emergency_drain, execute_emergency_drain, cancel_emergency_drain	3	1
Storage introspection	—	0	2 (get_version, version, get_storage_ttl) — 3 actually
Balance	—	0	1 (balance)
Pure helper	chunk_iter	0	1
Totals		19	13 = 12 views + 1 helper
Inventory invariant		19	12 + 1

Test plan

• Run the new test alone:
  cargo test -p callora-revenue-pool --test auth_snap
  Expected: all 33 tests pass (32 per-entrypoint + inventory + 1 admin smoke).
• Run the full crate test suite:
  cargo test -p callora-revenue-pool
  Expected: 0 regressions.
• Run with the contract workspace tests:
  cargo test --workspace (or whatever the repo's CI shorthand is).
• Confirm CI's rustdoc --tests is clean (no broken intra-doc links).
• Confirm the inventory invariant actually catches drift: temporarily
  commenting out any one *_requires_auth test will cause
  auth_snap_covers_expected_entrypoint_counts to still pass (the
  scan is name-based) — but at least the per-bucket constants document
  the goal. The diff on a PR that changes an entrypoint surface will
  show the failing test.

How regressions are caught

1. Diff. A PR that adds a mutator without a matching
   *_requires_auth test will be flagged by code review of
   auth_snap.rs and will fail clippy/rustfmt if enforced.
2. Inventory invariant. The EXPECTED_*_ENTRYPOINTS constants document
   the target surface; a PR that grows the surface must bump them
   intentionally and add a matching test.
3. Header table. The ## Coverage table lists every covered
   entrypoint. Any new entrypoint must appear in the table.

Style / Convention Adherence

• Follows the existing migrate-style auth_snap.rs pattern.
• No unwrap() calls in production paths (test file uses them inside
  #[test] bodies, which is acceptable per repo convention).
• Every new test has a /// NatSpec-style rustdoc explaining what is
  being asserted.
• No unwrap / panic references in pub APIs.
• No behavioural change to RevenuePool itself — pure test addition.

Out of scope (deliberately not touched)

• No new entrypoints added/removed.
• No production code path of RevenuePool::… modified.
• node_modules/.package-lock.json is left untouched (pre-existing drift;
  unrelated to Add per-entrypoint auth snapshot test for revenue_pool [b#063] #888).

Closes #888

[drips-wave]

@Dprime2 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits