refactor: reduce redundant storage reads in record_usage validation

[Baskarayelu]

Summary

Tightens and documents the validation chain in record_usage (contracts/escrow/src/lib.rs). This is a clarity/robustness refactor — the public API and all validation semantics and error precedence are unchanged.

Closes #30

What changed

• Added a documented comment block at the top of the validation chain spelling out the fixed error precedence:
  Paused(#4) -> ZeroRequests(#2) -> Max(#8) -> Min(#9) -> Registration(#7) -> Disabled(#12) -> Allowlist(#10).
• Annotated each conditional read so the gating is explicit:
  • ServiceRegistered is only read when RequireServiceRegistration is true (short-circuited via &&).
  • AgentAllowed is only read when AllowlistEnabled is true (short-circuited via &&).
• Confirmed that the max/min caps are cached in locals (read once, compared once) and that the usage counter is read exactly once. No value is read twice.

Read-count note (honest before/after)

The worst-case storage read count is unchanged — this PR does not remove any read. What it does:

• Confirms the two conditional reads (ServiceRegistered, AgentAllowed) were already correctly gated behind their controlling flags, so they never execute when those flags are off, and keeps that short-circuit.
• Documents the read order and gating inline so future edits do not accidentally promote a gated read to an unconditional one or reorder the precedence.
• The always-on reads (Paused, MaxRequestsPerCall, MinRequestsPerCall, ServiceDisabled) are unavoidable gates and remain; max/min remain cached in locals.

No reductions are claimed beyond confirming and preserving the existing conditional gating and local caching.

Security notes

• Error precedence is preserved exactly. New tests assert the ordering directly using #[should_panic(expected = "Error(Contract, #N)")]:
  • paused beats zero-requests (Emit structured events on admin, price, and registration state changes #4 not Add a reset_usage entrypoint to drain an agent-service counter without settling #2)
  • zero-requests beats max (Add a reset_usage entrypoint to drain an agent-service counter without settling #2)
  • max beats min (Manage persistent-entry TTL with explicit storage bumping #8)
  • min beats registration (Add a dispute-and-refund flow for contested usage records #9)
  • registration beats disabled (Add contract upgradeability via update_current_contract_wasm #7)
  • disabled beats allowlist (Add a paginated query entrypoint to enumerate an agent's active services #12)
• Plus per-gate trigger tests (Add contract upgradeability via update_current_contract_wasm #7 registration, Add a paginated query entrypoint to enumerate an agent's active services #12 disabled, Add per-agent, per-window rate limiting to record_usage #10 allowlist, Manage persistent-entry TTL with explicit storage bumping #8 max, Add a dispute-and-refund flow for contested usage records #9 min) and an all-gates-satisfied success path.

Tests

test result: ok. 63 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out