feat: add admin-gated decrement_usage for over-report corrections

[yunus-dev-codecrafter]

closes #83

feat: add admin-gated decrement_usage for over-report corrections

Summary

Adds a new decrement_usage(env, agent, service_id, amount) -> u32 entrypoint that lets the admin subtract an erroneous delta from a per-(agent, service_id) usage counter without discarding the legitimate remainder. Previously the only ways to lower a counter were settle/reset_usage, which wipe it entirely to zero.

Changes

contracts/escrow/src/lib.rs

• New decrement_usage entrypoint with validation order: paused → amount==0 → admin auth
• Uses saturating_sub — clamps at zero, never underflows
• Rejects amount == 0 with existing EscrowError::RequestsMustBePositive (code Add a reset_usage entrypoint to drain an agent-service counter without settling #2)
• Emits distinct usage_dec(agent, service_id, amount, new_total) event for audit trail
• Lifetime counters TotalUsageByAgent and TotalRequestsAllTime are not adjusted (raw analytics preserved)

contracts/escrow/src/test.rs
11 new tests covering all edge cases:

Test	Coverage
test_decrement_usage_basic	100→70, verify return + storage
test_decrement_usage_past_zero_clamps	50→200 saturates to 0
test_decrement_usage_to_zero	100→100 drains to 0
test_decrement_usage_never_used_clamps	absent pair → 0 no-op
test_decrement_usage_rejects_zero	amount=0 → #2
test_decrement_usage_rejects_non_admin	no auth → Unauthorized
test_decrement_usage_rejected_while_paused	paused → #4
test_decrement_usage_lifetime_counters_unchanged	TotalUsageByAgent & TotalRequestsAllTime preserved
test_decrement_usage_emits_event	Verify usage_dec payload
test_decrement_usage_paused_beats_zero	#4 beats #2 ordering
test_decrement_usage_zero_beats_noauth	#2 beats auth ordering

README.md

• Added "Correction flow: decrement_usage" section documenting the lifetime-counter policy

Security notes

• No underflow: uses saturating_sub — counter clamps at zero, never underflows
• Admin-only: require_auth on the stored admin address
• Auditable: distinct usage_dec event with (agent, service_id, amount, new_total) payload
• Zero rejected: amount == 0 is rejected with RequestsMustBePositive to prevent no-op corrections in the audit trail
• Lifetime counters preserved: TotalUsageByAgent and TotalRequestsAllTime are untouched so analytics retain the raw reported figure

Full cargo test output

running 182 tests
...
test result: ok. 182 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 7.50s

Verification

cargo fmt --all -- --check   ✅
cargo build                  ✅
cargo test                   ✅ (182/182 passing)

[mikewheeleer]

nice — a decrement_usage for over-reported usage is handy. lgtm 🙌